[NTG-context] [***SPAM***] OT: Generating Command reference from source code

Jan Tosovsky j.tosovsky at email.cz
Wed Dec 4 18:56:43 CET 2013


On 2013-12-04 Hans Hagen wrote:
> On 12/3/2013 10:59 PM, Jan Tosovsky wrote:
> >
> > 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.
> 
> there is a (somewhat incomplete) reference definition in xml format so
> your (b) is in principle covered; 

where is it stored?

> 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)

I was afraid of something like this :-(

In this case all the idea seems to be unrealistic.
 
> 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)
> 

A nice overview. I would add the ConTeXt mail archive to this list ;-)

Thanks for your exhaustive insight to this topic!

Jan



More information about the ntg-context mailing list