1. Documentation HTML errors
- Posted by ArthurCrump Aug 23, 2009
- 928 views
Clicking on 'Manual' from the forum gives a document with errors.
Several routines and other identifiers are headed 'Unknown', including the routine 'allocate_string' which I found eventually.
Another error is that several of these allocate_* routines are documented as being in memory.e but are actually in machine.e
I have not reported this as a Euphoria bug because it cannot be expected to affect the release of beta 2.
Arthur Crump
2. Re: Documentation HTML errors
- Posted by jeremy (admin) Aug 23, 2009
- 916 views
It would still be nice to have exact errors in the bug system so they can be fixed by the time 4.0b3 is released. Most doc bugs are easily fixed and it's very possible to make the fix to the manual before 4.0b2.
Can you give specific examples of where these Unknown routines appear? For instance, a URL would be very helpful.
Jeremy
3. Re: Documentation HTML errors
- Posted by ArthurCrump Aug 23, 2009
- 982 views
It would still be nice to have exact errors in the bug system so they can be fixed by the time 4.0b3 is released. Most doc bugs are easily fixed and it's very possible to make the fix to the manual before 4.0b2.
Can you give specific examples of where these Unknown routines appear? For instance, a URL would be very helpful.
Jeremy
The Euphoria manual has a number of routines and constants identified by 'Unknown'.
This has caused me to refer to the wrong section for one routine.
I have now scanned the manual for other occurrences.
The HTML files involved are
http://openeuphoria.org/docs/eu400_nnnn.htm
where there are 'Unknown's in nnnn values of
0051, 0052, 0055, 0061, 0063, 0085, 0086, 0090, 0093,
0094, 0095, 0096, 0097, 0100, 0104, 0106 and 0107.
Probably more useful are the section numbers:
8.1.1.18, 8.4.1.7, 8.4.5.16, 8.10.1.2, 8.12.1.5, 8.12.1.6
12.1.1.7, 12.1.1.8, 12.1.1.9, 12.1.1.10, 12.1.1.11
13.3.0.5, 13.4.3.4, 13.5.0.2, 13.5.0.4, 13.5.1.1, 13.5.2.1, 13.6.2.1, 13.6.2.5
14.0.2.28, 15.4.0.3, 15.4.0.10, 16.1.3.7
I have just tried to get into the bug reporting system and would probably need to find out how to report a bug before using that, sorry.
Arthur
4. Re: Documentation HTML errors
- Posted by ne1uno Aug 24, 2009
- 881 views
It would still be nice to have exact errors in the bug system so they can be fixed by the time 4.0b3 is released. Most doc bugs are easily fixed and it's very possible to make the fix to the manual before 4.0b2.
The Euphoria manual has a number of routines and constants identified by 'Unknown'.
This has caused me to refer to the wrong section for one routine.
it's easy enough to find undocumented with grep if you have all the html in one place.
@echo grep for Undocumented >un.txt %grep% -n -l -c -i "Undocumented" eu4*.html >>un.txt %grep% -C3 -i "Undocumented" eu4*.html >>un.txt
there are some genuine undocumented functions. you would see the include file and a function signature followed by "undocumented". there are a few cases where one routine, constant or builtin is documented but through markup or eudoc error the next function becomes the function signature before the documented one. eudoc should probably make a page of any undocumented or unknown links as an option.
the goal of keeping the documentation with the code breaks down a little with the memory rountines and builtins because of SAFE. with eu4 you always only include std/machine.e
the commandline option -D SAFE or with define SAFE in a program will include memory.e or safe.e as required.
eudoc currently has no way to specify the include file or to exclude sections of comments, so the docs appear to suggest include std/memory.e or std/safe.e might be necessary. as well as presenting many more export and override routiines & constants to search through than anyone not maintaining euphoria itself would ever use. you also have something like peeks undocumented under safe.e while referenced as a builtin elsewhere.
it might be better to remove std/safe,e and std/memory,e from eudoc scanning. move all the documentation about builtins currently in std/machine.e to docs/memory.txt and present a simpler reference to what is available.
meantime, the fix for a few of the undocumeted were some excess blank lines. allocate_string was moveed around without also moving the matching doc comments. fix will be in the next beta and next online doc generation.
5. Re: Documentation HTML errors
- Posted by ne1uno Aug 25, 2009
- 856 views
The Euphoria manual has a number of routines and constants identified by 'Unknown'.
thanks for the bug report. try again in b2.
most of the "unknown" were caused by a variety of eudoc markup errors or quirks. the few remaining probably could be fixed with some code reformatting, but it is ultimately a bug in eudoc or the tokenizers handling of constant declarations. when more coders start using eudoc in their own projects they will probably expect any valid euphoria syntax to be handled.
