On 12/3/2013 10:59 PM, Jan Tosovsky wrote:
Dear All,
in another thread I was dreaming ... to have always the complete and up to
date command/macro reference with basic descriptions and list all of the
parameter/options...
'Spoiled' by goodies offered by various Java APIs (based on
http://en.wikipedia.org/wiki/Javadoc ) I am missing this a lot.
Example of the result:
http://docs.oracle.com/javase/7/docs/api/index.html?overview-summary.html
In Java there is the following structure (simplified):
1) 'packages' defining the hierarchy
2) 'classes' defining objects
3) 'properties' and 'methods' for every particular 'class'
I've roughly scanned the ConTeXt source structure and bringing the following
idea:
1) There is no 'packages' counterpart in ConTeXt, but it would be handy to
think of any logical structure to group commands to logical groups (even
nested). Maybe the filename title prefix could be taken as a starting point
for this.
2) 'classes' = all individual .mkiv files
3) 'methods' = all public \def, \define etc in mkiv files (+maybe other
contructs I am not aware)
Supposing that ...
a) every .mkiv file is enhanced by 'package' annotation
b) every public command/macro contains a description with the list of all
available params
(sensible subset of JavaDoc annotations)
.... I can imagine to extract this info and:
A) build the static command reference website with all the hyperlinks
B) eventually generate PDF variant of the same
C) export it into the form which can be imported into the WIKI (with
read-only mode)
If every change of behaviour was reflected immediately in the description,
if any newly added parameter was added into the parameter list, the main
goal would be achieved.
keep in mind that quite some functionality is the result of user
requests and for a while can be in flux and i consider it then the users
responsibility to wrap up on the wiki (for completely new mechanisms i
often write a dedicated manual or an article for a user group journal)
But I understand there is lot of to do in the beginning... with disputable
effect in the end.
I can help with some coding, transforming ...
Jan
Btw, would it be sufficient to scan texmf-context\tex\context\base\*.mkiv
files or there are other parts somewhere else? There are approx 500 files
now. It is huge number, but finite :-)
there is a (somewhat incomplete) reference definition in xml format so
your (b) is in principle covered; these definitions used to be in the
source (more than a decade ago) but i moved them out because some
functionality is stepwise provided (not in one place) and also because
many commands are generated (you will not find their names by
interpreting the source)
the problem with tex (and therefore context) is that we are dealing with
quite some interaction between unpredictable user input, macro
(expansions), tex-internals, resources like fonts, patterns and
whatever, etc. and this is why you often need to play with mechanisms:
small test files and see how it looks (tex is a visual tool)
it's often not as simple as "you feed it this" end "get back that"
for documentation several methods are used:
- examples in the test suite
- some explanation in the source
- explanations on the wiki
- dedicated manuals
- articles by users (+examples)
although i sometimes run into impressive auto-documented documentation
for languages or os commands, in practice i find myself looking for
examples and/or experimenting and/or going into sources
Hans
-----------------------------------------------------------------
Hans Hagen | PRAGMA ADE
Ridderstraat 27 | 8061 GH Hasselt | The Netherlands
tel: 038 477 53 69 | voip: 087 875 68 74 | www.pragma-ade.com
| www.pragma-pod.nl
-----------------------------------------------------------------
___________________________________________________________________________________
If your question is of interest to others as well, please add an entry to the
Wiki!
maillist : ntg-context@ntg.nl / http://www.ntg.nl/mailman/listinfo/ntg-context
webpage : http://www.pragma-ade.nl / http://tex.aanhet.net
archive : http://foundry.supelec.fr/projects/contextrev/
wiki : http://contextgarden.net
___________________________________________________________________________________
