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