#4751: improve documentation generation
-------------------------------------------------+-------------------------
Reporter: Forgon | Owner:
Type: patch (an actual patch, not a | Status: new
request for one) | Milestone:
Priority: normal | unspecified
Component: other | Version:
Keywords: | git/master
Blocking: | Blocked By:
| Operating System: All
| /Non-Specific
-------------------------------------------------+-------------------------
=== Man page ===
When executing `a2x -f manpage -D . ./warzone2100.6.asciidoc`, Asciidoc
prints a warning:
{{{
a2x: WARNING: --destination-dir option is only applicable to HTML based
outputs
}}}
[https://github.com/asciidoc/asciidoc/issues/44 This is an inconsequential
error], which can be suppressed by instead executing `a2x -f manpage
./warzone2100.6.asciidoc`, which is functionally equivalent.
=== JavaScript API reference ===
The JavaScript API reference is generated with the following commands:
{{{
grep ./src/qtscript.cpp -e '//==' | sed 's/\/\/==//' > doc/globals.tex
grep ./src/qtscriptfuncs.cpp -e '//==' | sed 's/\/\/==//' >>
doc/globals.tex
grep ./src/qtscript.cpp -e '//__' | sed 's/\/\/__//' > doc/events.tex
grep ./src/qtscript.cpp -e '//--' | sed 's/\/\/--//' > doc/functions.tex
grep ./src/qtscriptfuncs.cpp -e '//--' | sed 's/\/\/--//' >>
doc/functions.tex
grep ./src/qtscriptfuncs.cpp -e '//;;' | sed 's/\/\/;;//' >
doc/objects.tex
grep ./data/base/script/campaign/libcampaign.js -e '//;;' | sed
's/\/\/;;//' > doc/campaign.tex
test /home/x/warzone2100-backup/warzone2100 =
/home/x/warzone2100-backup/warzone2100 || cp ./doc/javascript.tex doc/
}}}
Sed substitution commands are now delimited with a colon rather than a
dash, which renders escape characters obsolete and improves readability.
{{{
(cd doc; hevea javascript.tex; hevea javascript.tex)
./javascript.tex:4: Warning: Command not found: \lstloadlanguages
./javascript.tex:10: Warning: No author given
./javascript.tex:28: Warning: keyval, unknown key: 'AI'
./javascript.tex:75: Warning: keyval, unknown key: 'scripts'
./javascript.tex:86: Warning: keyval, unknown key: 'player_2'
./functions.tex:149: Warning: Undefined label: 'objects:structure'
./functions.tex:156: Warning: Undefined label: 'objects:structure'
HeVeA Warning: Label(s) may have changed. Rerun me to get cross-references
right.
./javascript.tex:4: Warning: Command not found: \lstloadlanguages
./javascript.tex:10: Warning: No author given
./javascript.tex:28: Warning: keyval, unknown key: 'AI'
./javascript.tex:75: Warning: keyval, unknown key: 'scripts'
./javascript.tex:86: Warning: keyval, unknown key: 'player_2'
HeVeA Warning: Label(s) may have changed. Rerun me to get cross-references
right.
(cd doc; hacha -o javascript-index.html javascript.html)
}}}
The command '\lstloadlanguages' is not found because HeVea implements only
a subset of the [https://ctan.org/pkg/listings LaTeX package "listings"]
(read [http://hevea.inria.fr/doc/manual-packages.html#listings%3Apackage
this section for more details]) to which it belongs.
All references to programming languages have been removed since
JavaScript, JSON and INI are not in the list of languages supported by
"listings" (read page 13 of its
[http://mirror.ox.ac.uk/sites/ctan.org/macros/latex/contrib/listings/listings.pdf
documentation]). These languages could be defined (read section 3.2 of the
User's guide in the documentation), yet this would unlikely be worth the
necessary effort since the JavaScript API documentation will soon be
converted from LaTeX to Markdown.
In 3 cases, literal square brackets were confused with optional
environment arguments, as in this example:
{{{
\begin{lstlisting}
[AI]
name = "Semperfi JS"
js = semperfi.js
\end{lstlisting}
}}}
The problem was solved by declaring the "lstlisting" environment with an
empty set of optional arguments.
The warning about no author being given was suppressed by declaring
'\author{}' with an empty set of names.
Warnings about undefined labels commonly occur in LaTeX even in the
absence of syntax errors. In such cases, the proper way to fix them when
using HeVeA is to execute `hevea -fix <file>` rather than running the
program several times.
The only label used in the JavaScript API documentation was renamed from
"objects:structure" to "subsec:Structure", which is more in line with
LaTeX conventions.
--
Ticket URL: <http://developer.wz2100.net/ticket/4751>
Warzone 2100 Trac <http://developer.wz2100.net/>
The Warzone 2100 Project
------------------------------------------------------------------------------
Check out the vibrant tech community on one of the world's most
engaging tech sites, Slashdot.org! http://sdm.link/slashdot
_______________________________________________
Warzone2100-project mailing list
Warzone2100-project@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/warzone2100-project
