Wiki improvements

Forum for discussion about the documentation project.
Post Reply
fxm
Moderator
Posts: 12197
Joined: Apr 22, 2009 12:46
Location: Paris suburbs, FRANCE

Re: Wiki improvements

Post by fxm »

SARG wrote: Jan 27, 2023 14:37
fxm wrote: Jan 27, 2023 12:50 For these HTML warnings, I do not see what I can do about it
Me too :D
As I don't how you create the pages I can't say if there is a way. Maybe a special tag exists disabling the normal tags.

In the ProPgConstantExpressions page for example, the affected elements are already between 2 double quotes on each side:
Only the following operators/functions with constant arguments can be used to constitute constant expressions:
##""Bit"", ""BitReset"", ""BitSet"", ""HiByte"", ""HiWord"", ""LoByte"", ""LoWord""
""+"", ""-"", ""*"", ""/"", ""\"", ""^"", ""Mod"", ""Shl"", ""Shr""
""="", ""<>"", ""<="", "">="", ""<"", "">""
""And"", ""Eqv"", ""Imp"", ""Or"", ""Not"", ""Xor""
""Abs"", ""Acos"", ""Asin"", ""Atan2"", ""Atn"", ""Cos"", ""Exp"", ""Fix"", ""Frac"", ""Int"", ""Log"", ""Sgn"", ""Sin"", ""Sqr"", ""Tan""
""Asc"", ""Chr"", ""CVD"", ""CVI"", ""CVL"", ""CVLongInt"", ""CVS"", ""CVShort"", ""Len"", ""SizeOf""
""Cast"", ""CBool"", ""CByte"", ""CDbl"", ""CInt"", ""CLng"", ""CLngInt"", ""CShort"", ""CSign"", ""CSng"", ""CUByte"", ""CUInt"", ""CULng"", ""CULngInt"", ""CUnsg"", ""CUShort""
**more obviously all predefined symbols**##
adeyblue
Posts: 304
Joined: Nov 07, 2019 20:08

Re: Wiki improvements

Post by adeyblue »

I mean, it's pretty obvious that the problem is that the wiki php rendering translates the raw '<' in the pages to '&lt;' to make it valid HTML but the local building process doesn't - hence why it complains about invalid HTML, because it is.
coderJeff
Site Admin
Posts: 4358
Joined: Nov 04, 2005 14:23
Location: Ontario, Canada
Contact:

Re: Wiki improvements

Post by coderJeff »

To quiet the warnings/errors in the html/chm generation, only two lines need be changed in the fbdoc generator:
https://github.com/freebasic/fbc/blob/3 ... .bas#L1138
https://github.com/freebasic/fbc/blob/3 ... .bas#L1205
Making those changes will call a function Text2Html() to escape certain characters to valid html.

But if we do that, then there is some other work to do to clean up the workarounds that have been used in the past. Really old versions of the wiki only handled ascii text and therefore also fbdoc generator too, so we used a couple of different hacks to try and work around lack of unicode support in fbc and wiki.

For example: ASC page has this line which injects html directly in to the html/chm output:
a = "&#1055;&#1088;&#1080;&#1074;&#1077;&#1090;, &#1084;&#1080;&#1088;"

But with the changes above in "CWakka2Html.bas" it would be escaped and shown as is which we don't want, so should be changed to the utf-8 representation on the wiki page itself:
a = "Привет, мир"

Even though fbdoc uses STRING data type to handle all text, any utf-8 from the wiki should survive for most of the operations we need to do with it.
But CptAscii needs special handling, and also and code examples that are automatically extracted from the wiki in to the examples directory. So there will be updates needed on some of the other documentation support tools too.
fxm
Moderator
Posts: 12197
Joined: Apr 22, 2009 12:46
Location: Paris suburbs, FRANCE

Re: Wiki improvements

Post by fxm »

In the Programmer's Guide, FAQ#12 and FAQ#13 from the former Critical Sections FAQ have been moved to a new Emulate a TLS (Thread Local Storage) and a TP (Thread Pooling) feature page in the 'Technical Articles' section:
  • ProPgEmulateTlsTp → fxm [Critical Sections FAQ#12 and FAQ#13 transferred to a new 'Emulate a TLS (Thread Local Storage) and a TP (Thread Pooling) feature' page in the 'Technical Articles' part of the Programmer's Guide]
  • CatPgProgrammer → fxm [added link to 'Emulate a TLS (Thread Local Storage) and a TP (Thread Pooling) feature']
  • ProPgMtCriticalSections → fxm [added link to 'Emulate a TLS (Thread Local Storage) and a TP (Thread Pooling) feature']
  • ProPgMtCriticalSectionsFAQ → fxm [added link to 'Emulate a TLS (Thread Local Storage) and a TP (Thread Pooling) feature']
  • PrintToc → fxm [added link to 'Emulate a TLS (Thread Local Storage) and a TP (Thread Pooling) feature']
These two former FAQs are rather advanced features than simple asked questions.
fxm
Moderator
Posts: 12197
Joined: Apr 22, 2009 12:46
Location: Paris suburbs, FRANCE

Re: Wiki improvements

Post by fxm »

fxm wrote: May 02, 2023 12:04 In the Programmer's Guide, FAQ#12 and FAQ#13 from the former Critical Sections FAQ have been moved to a new Emulate a TLS (Thread Local Storage) and a TP (Thread Pooling) feature page in the 'Technical Articles' section .....

@Jeff,

I did not rename the filenames of concerned examples, otherwise I would create orphaned files unless I give you a list of files to delete after renaming the example files.
coderJeff
Site Admin
Posts: 4358
Joined: Nov 04, 2005 14:23
Location: Ontario, Canada
Contact:

Re: Wiki improvements

Post by coderJeff »

fxm wrote: May 07, 2023 14:42
fxm wrote: May 02, 2023 12:04 In the Programmer's Guide, FAQ#12 and FAQ#13 from the former Critical Sections FAQ have been moved to a new Emulate a TLS (Thread Local Storage) and a TP (Thread Pooling) feature page in the 'Technical Articles' section .....

@Jeff,

I did not rename the filenames of concerned examples, otherwise I would create orphaned files unless I give you a list of files to delete after renaming the example files.
You should go ahead and rename the files as needed. We won't lose anything. Ideally, either change the file contents or rename the file, but not both in the same snapshot. But if both changed and renamed, that's ok too (see below).

We can synchronize the wiki page examples and repository files using 'samps' - a command line wiki management tool written years ago that will compare the wiki page contents and the ./examples/manual files and read/write content/files. Orphaned files can be detected but won't be automatically deleted.

To check for changes / new example files, the check is based on a list of pages to scan and compared against examples/manual:
samps check [pages...] [@pagelist]
(checks for differences between pages and files)

To check for orphaned (dropped) examples, check is based on sub directories of ./examples/manual and compared against page contents:
samps checkex [dirs...]
(checks for dropped example files)

And, if example file is only moved or renamed, then git will detect that the example was moved / renamed and continuity of revision history for that file will be maintained in the git repository too. If the example is moved or renamed and also changed, git might detect that it the same file, but only if changes are very minor.
srvaldez
Posts: 3401
Joined: Sep 25, 2005 21:54

Re: Wiki improvements

Post by srvaldez »

hello fxm :)
on Jul 05, 2023 dodicat posted a small example using the legacy screen 0 viewtopic.php?p=299634#p299634
I tried to find information about screen 0 in the manual but it seems to be absent, perhaps I missed it?
Imortis
Moderator
Posts: 1929
Joined: Jun 02, 2005 15:10
Location: USA
Contact:

Re: Wiki improvements

Post by Imortis »

https://www.freebasic.net/wiki/KeyPgScreengraphics

There is a small section on screen 0 here.
deltarho[1859]
Posts: 4320
Joined: Jan 02, 2017 0:34
Location: UK
Contact:

Re: Wiki improvements

Post by deltarho[1859] »

srvaldez wrote:I tried to find information about screen 0 in the manual but it seems to be absent, perhaps I missed it?
Open the manual and do a search for "screen 0" (Not screen 0)

Of the entries, click on Screen( Graphics ).

About half way down is: Note on using Screen 0 (text mode only)

That is the same paragraph as in the WiKi.
fxm
Moderator
Posts: 12197
Joined: Apr 22, 2009 12:46
Location: Paris suburbs, FRANCE

Re: Wiki improvements

Post by fxm »

Same search syntax ("screen 0") on the Wiki.
https://www.freebasic.net/wiki/wikka.ph ... creen+0%22
srvaldez
Posts: 3401
Joined: Sep 25, 2005 21:54

Re: Wiki improvements

Post by srvaldez »

mode 0 is missing from the more detailed list, it starts with 1 and onward
fxm
Moderator
Posts: 12197
Joined: Apr 22, 2009 12:46
Location: Paris suburbs, FRANCE

Re: Wiki improvements

Post by fxm »

srvaldez wrote: Jul 08, 2023 13:58 mode 0 is missing from the more detailed list, it starts with 1 and onward

Because the title of the page is:
SCREEN (GRAPHICS)

It is why I only added a note about 'Screen 0'.
srvaldez
Posts: 3401
Joined: Sep 25, 2005 21:54

Re: Wiki improvements

Post by srvaldez »

fxm, never mind, I should not have bothered you :oops:
fxm
Moderator
Posts: 12197
Joined: Apr 22, 2009 12:46
Location: Paris suburbs, FRANCE

Re: Wiki improvements

Post by fxm »

fxm wrote: Jul 08, 2023 14:03
srvaldez wrote: Jul 08, 2023 13:58 mode 0 is missing from the more detailed list, it starts with 1 and onward

Because the title of the page is:
SCREEN (GRAPHICS)

It is why I only added a note about 'Screen 0'.

... and I added an info under the first table:
- KeyPgScreengraphics → fxm [quoted SCREEN 0]
srvaldez
Posts: 3401
Joined: Sep 25, 2005 21:54

Re: Wiki improvements

Post by srvaldez »

thank you fxm :)
Post Reply