Hi all, Not sure how many of you remember this, but at the Kalenberg meeting in 2016 there was this talk: =========== Setups Wolfgang Schuster (and Hans Hagen) The user interface is described in xml files but the actual descriptions lagged behind development. Wolfgang spent a considerable amount of time to describe all commands in detail and we updated the descriptive format in the process. The rendering was partly redone, as was the help system and scripts that use this information. =========== Since then, nothing much had been done with those updated xml files, which is a big shame considering the enormous amount of work that went into the process. But recently we have been discussing the wiki and (especially) the sorry state of the reference portion of that. At some point, I realised that we could rather easily combine the new xml interface files with a small wiki extension, such that the wiki has easy access to the latest and greatest command list. =========== From now on, when you are editing the wiki (especially the /Command/CMD pages), you can use <syntax>CMD</syntax> to output the formal table of arguments for that CMD (omit the backslash) For example, <syntax>section</syntax> outputs a table with the formal calling convention(s) for the \section command. Multiple tables actually, as it also outputs the alternative calls with different arguments, and it outputs the definition of the internal \*section* command, of which \section is an instance. (The parents of instances are printed in a slanted font). There are 2035 normal commands and 373 instances in the database, essentially covering all the style- and document-level commands in ConTeXt. I’ve decided not to add the low-level system commands because (apart from perhaps a few special cases) these do not belong in general user documentation. =========== I have not auto-replaced any of the handcrafted command page syntax tables in the existing wiki pages, because quite often the current syntax table has manual additions explaining various options. In the formal version these are obviously not present, and I did not want to remove any of that extra information. Anyway, the nice thing about this new wiki plugin is that if you want to create a page for a specific command that is not in existence right now, it is a simple matter of going to the expected url, and creating a page with just a Syntax heading and a <syntax> tag. For example (created a minute ago): url: https://wiki.contextgarden.net/Command/setupdescription content: == Syntax == <syntax>setupdescription</syntax> Thanks go to Wolfgang for all the hard work! Best wishes, Taco
Am 30.05.19 um 12:07 schrieb Taco Hoekwater:
url: https://wiki.contextgarden.net/Command/setupdescription
content: == Syntax ==
<syntax>setupdescription</syntax>
Brilliant! Thanks a lot! juh
Hello Taco,
From now on, when you are editing the wiki (especially the /Command/CMD pages), you can use <syntax>CMD</syntax> to output the formal table of arguments for that CMD (omit the backslash)
For example,
<syntax>section</syntax>
outputs a table with the formal calling convention(s) for the \section command. Multiple tables actually, as it also outputs the alternative calls with different arguments, and it outputs the definition of the internal \*section* command, of which \section is an instance. (The parents of instances are printed in a slanted font).
this is really great! This gives idea what syntax "sugars" (alternatives) are possible and what args may be used! This lacked for years!
===========
I have not auto-replaced any of the handcrafted command page syntax tables in the existing wiki pages, because quite often the current syntax table has manual additions explaining various options. In the formal version these are obviously not present, and I did not want to remove any of that extra information.
Anyway, the nice thing about this new wiki plugin is that if you want to create a page for a specific command that is not in existence right now, it is a simple matter of going to the expected url, and creating a page with just a Syntax heading and a <syntax> tag.
For example (created a minute ago):
url: https://wiki.contextgarden.net/Command/setupdescription
content: == Syntax ==
<syntax>setupdescription</syntax>
My suggestions is to add an auto-generated-command-syntax wiki-page-section, too. I find it very useful - just now one can see what are possibilities! I added the following code into wiki page - just for testing purposes, anyone can alter the page: https://wiki.contextgarden.net/Command/section#Syntax ---- <hr/> == [[Help:Reference|Syntax (generated automatically from ConTeXt definition)]] == <syntax>section</syntax> <hr/> ---- And just now I can see that \section accepts syntax of the forms: \section[MyRef]{My title} \section[MyRef]{4.0}{My title} \section[reference=MyRef,ownnumber=4.0,title={My title}] So better for us if we find a way to COMBINE command descriptions already existing on wiki WITH those generated via <syntax>command</syntax> injection. Thanks again for the great job. Best regards, Lukas
Thanks go to Wolfgang for all the hard work!
Best wishes, Taco
-- Ing. Lukáš Procházka | mailto:LPr@pontex.cz Pontex s. r. o. | mailto:pontex@pontex.cz | http://www.pontex.cz | IDDS: nrpt3sn | IČO: 40763439 Bezová 1658 147 14 Praha 4 Mob.: +420 702 033 396
On 5/30/2019 12:07 PM, Taco Hoekwater wrote:
I have not auto-replaced any of the handcrafted command page syntax tables in the existing wiki pages, because quite often the current syntax table has manual additions explaining various options. In the formal version these are obviously not present, and I did not want to remove any of that extra information.
maybe at some point we can have extra xml files that explain some of that (after all there is a 'xml path' to such an entry ... something to discuss at a meeting
Anyway, the nice thing about this new wiki plugin is that if you want to create a page for a specific command that is not in existence right now, it is a simple matter of going to the expected url, and creating a page with just a Syntax heading and a <syntax> tag.
For example (created a minute ago):
url: https://wiki.contextgarden.net/Command/setupdescription
content: == Syntax ==
<syntax>setupdescription</syntax>
Thanks go to Wolfgang for all the hard work! And you too!
Hans ----------------------------------------------------------------- Hans Hagen | PRAGMA ADE Ridderstraat 27 | 8061 GH Hasselt | The Netherlands tel: 038 477 53 69 | www.pragma-ade.nl | www.pragma-pod.nl -----------------------------------------------------------------
On 30 May 2019, at 12:07, Taco Hoekwater
wrote: […] For example,
<syntax>section</syntax>
outputs a table with the formal calling convention(s) for the \section command. Multiple tables actually, as it also outputs the alternative calls with different arguments, and it outputs the definition of the internal \*section* command, of which \section is an instance. (The parents of instances are printed in a slanted font).
This is absolutely magic and extremely useful! Thank you, Wolfgang, Taco and Hans! I wonder whether the magic behind the scenes would allow some day to say \syntax[section] within a ConTeXT document… :-) Best regards, and again many many thanks: OK
On 5/30/2019 9:34 PM, Otared Kavian wrote:
On 30 May 2019, at 12:07, Taco Hoekwater
wrote: […] For example,
<syntax>section</syntax>
outputs a table with the formal calling convention(s) for the \section command. Multiple tables actually, as it also outputs the alternative calls with different arguments, and it outputs the definition of the internal \*section* command, of which \section is an instance. (The parents of instances are printed in a slanted font).
This is absolutely magic and extremely useful! Thank you, Wolfgang, Taco and Hans!
I wonder whether the magic behind the scenes would allow some day to say \syntax[section] within a ConTeXT document… :-)
\usemodule[setups-basics] \loadsetups[i-context] \starttext \basicsetup{section:instance} \shortsetup{section:instance} \showsetup {section:instance} \stoptext ----------------------------------------------------------------- Hans Hagen | PRAGMA ADE Ridderstraat 27 | 8061 GH Hasselt | The Netherlands tel: 038 477 53 69 | www.pragma-ade.nl | www.pragma-pod.nl -----------------------------------------------------------------
participants (5)
-
Hans Hagen
-
Jan U. Hasecke
-
Otared Kavian
-
Procházka Lukáš Ing.
-
Taco Hoekwater