man pages for ConTeXt: looking for volunteers
Dear users, In preparation of this year's TeX Live release, it would be nice to also revise man pages a bit. Hans just implemented auto-conversion of help into man pages for the lua scripts. So the options are described as they should be, but if there are any volunteers to help polishing out and provide either more extensive descriptions, examples, ... or overall improvements, you are invited to leave some feedback or provide some help (additional text/descriptions or syntax corrections). The old man pages are at http://svn.contextgarden.net/suite/man/ and the new (possibly still experimental) man pages are now part of ConTeXt (see doc/context/scripts). Mojca
On 2013–03–21 Mojca Miklavec wrote:
In preparation of this year's TeX Live release, it would be nice to also revise man pages a bit.
Hans just implemented auto-conversion of help into man pages for the lua scripts. So the options are described as they should be, but if there are any volunteers to help polishing out and provide either more extensive descriptions, examples, ... or overall improvements, you are invited to leave some feedback or provide some help (additional text/descriptions or syntax corrections).
Just a small correction in mtxrun.{xml,man,html}: --timedrun run a script an time its run This should be rephrased, although I don't have suggestions since I have no clue what this option is for. Marco
Mojca wrote:
Hans just implemented auto-conversion of help into man pages for the lua scripts.
but if there are any volunteers to help polishing out and provide either more extensive descriptions, examples, ... or overall improvements,
An excellent idea. To cut the work into bite-sized pieces: over the coming weeks, I will post these files on the list one by one and solicit specific improvements / check for befuddlement. First, though, I have some questions: 1. I assume the man pages are created from the XML files, and we should edit the XML files -- is this correct? 2. Is the XML-to-man script included in the distribution? That would (a) make it easier to check the result of an edit, and (b) make it easier to find the answer to question 3 for myself. ;-) 3. Is there a key to specify bold and italic in the XML? (\fB...\fP and \fI...\fP in the man page.) Or, if you want to keep it semantic: are <code> (\fB) and <emph> (\fI, or also \fB) supported? 4. I really really like the <subcategory> groupings of the flags in the XML files. This useful grouping doesn't show up in the man pages, however. Perhaps the end of a subcategory could correspond to .TP ---- in the man pages? 5. Lastly, I think it would be good to include a standard SEE ALSO block at the end of each man page, to list all the scripts we have man pages for. This will make it easier for users to discover the man pages. Example below. If such a block could be supported, I would be happy to write it. <seealsos> <seealso name=mtx-grep> <short></short> </seealso> </seealsos> Cheers, Sietse
On 3/21/2013 3:44 PM, Sietse Brouwer wrote:
Mojca wrote:
Hans just implemented auto-conversion of help into man pages for the lua scripts.
but if there are any volunteers to help polishing out and provide either more extensive descriptions, examples, ... or overall improvements,
An excellent idea. To cut the work into bite-sized pieces: over the coming weeks, I will post these files on the list one by one and solicit specific improvements / check for befuddlement. First, though, I have some questions:
1. I assume the man pages are created from the XML files, and we should edit the XML files -- is this correct?
no, they are (since yesterday) generated from the scripts themselves: mtxrun --script fonts --exporthelp=man|xml|html|all
2. Is the XML-to-man script included in the distribution? That would (a) make it easier to check the result of an edit, and (b) make it easier to find the answer to question 3 for myself. ;-)
they are in the scripts ... the helpinfo is a xml blob in the script and that one is the base for help info ... so, any 'fixes' have to go in there
3. Is there a key to specify bold and italic in the XML? (\fB...\fP and \fI...\fP in the man page.) Or, if you want to keep it semantic: are <code> (\fB) and <emph> (\fI, or also \fB) supported?
no, we keep it simple ... all we can do is make the to-man converter better if needed
4. I really really like the <subcategory> groupings of the flags in the XML files. This useful grouping doesn't show up in the man pages, however. Perhaps the end of a subcategory could correspond to
i must say that i have no clue what the man pages look like but suggestions are welcome
.TP ----
in the man pages?
just tell me what to do
5. Lastly, I think it would be good to include a standard SEE ALSO block at the end of each man page, to list all the scripts we have man pages for. This will make it easier for users to discover the man pages. Example below. If such a block could be supported, I would be happy to write it.
<seealsos> <seealso name=mtx-grep> <short></short> </seealso> </seealsos>
sure, we can add stuff 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 -----------------------------------------------------------------
participants (4)
-
Hans Hagen -
Marco Patzer -
Mojca Miklavec -
Sietse Brouwer