Software manual template request

Software manual template request

[Vyatcheslav Yatskovsky]

Hello,

Does anyone has a template for software manual? I have vague notion
about how it should look like, but, well,  I'll know when I see it.
;o) Most modern manuals have common design elements; I wish I had
an environment which captures the spirit.

Needless to say, untouched LuaTex envinroment gives too much academic look.

Can anyone kindly suggest something?

Best regards,
Vyatcheslav Yatskovsky





___________________________________________________________________________________
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  : https://foundry.supelec.fr/projects/contextrev/
wiki     : http://contextgarden.net
___________________________________________________________________________________

Re: Software manual template request

[Aditya Mahajan]

On Mon, 31 Mar 2008, Vyatcheslav Yatskovsky wrote:

> Hello,
>
> Does anyone has a template for software manual? I have vague notion
> about how it should look like, but, well,  I'll know when I see it.
> ;o) Most modern manuals have common design elements; I wish I had
> an environment which captures the spirit.
>
> Needless to say, untouched LuaTex envinroment gives too much academic look.
>
> Can anyone kindly suggest something?

Most of the manuals of GNU software are written using texinfo. The 
advantage is that it is easy to get HTML and info output. There is also 
docbook, which offers some features for documenting code.

Both of them have fairly simple look, so it should be easy to create a 
ConTeXt module for them.

Aditya
___________________________________________________________________________________
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  : https://foundry.supelec.fr/projects/contextrev/
wiki     : http://contextgarden.net
___________________________________________________________________________________

Re: Software manual template request

[Taco Hoekwater]

Aditya Mahajan wrote:
> On Mon, 31 Mar 2008, Vyatcheslav Yatskovsky wrote:
> 
>> Hello,
>>
>> Does anyone has a template for software manual? I have vague notion
>> about how it should look like, but, well,  I'll know when I see it.
>> ;o) Most modern manuals have common design elements; I wish I had
>> an environment which captures the spirit.
>>
>> Needless to say, untouched LuaTex envinroment gives too much academic look.
>>
>> Can anyone kindly suggest something?
> 
> Most of the manuals of GNU software are written using texinfo. The 
> advantage is that it is easy to get HTML and info output. There is also 
> docbook, which offers some features for documenting code.
> 
> Both of them have fairly simple look, so it should be easy to create a 
> ConTeXt module for them.

If anybody knows of a API documentation style that can handle functions
that both take variable arguments as well as return variable arguments,
I am very interested in that. For example, there is a the luatex lua
function tex.print, and it accepts the following types of calls:

   tex.print("string", ... )  -- multiple string args are possilbe
   tex.print(number, "string", ... ) -- number is catcode table

And this is not a complex function at all. Here is kpse.find_file:

   f = kpse.find_file("filename")
   f = kpse.find_file("filename", 'ftype')
   f = kpse.find_file("filename", mustexist)
   f = kpse.find_file("filename", 'ftype', mustexist)
   f = kpse.find_file("filename", 'ftype', dpi)

* "filename" must be a string, otherwise an error is generated
* 'ftype'    must be one specific value from an enumeration list,
              default "tex"
* mustexist  must be a boolean, default false
* dpi        must be a number, and only applies if 'ftype' is
              'pk', 'gf', or 'bitmap font'. It is the "bitmap size".

* f          can either become a string, or nil

It is quite hard to find a suitable documentation style for such
functions.

Best wishes,
Taco
___________________________________________________________________________________
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  : https://foundry.supelec.fr/projects/contextrev/
wiki     : http://contextgarden.net
___________________________________________________________________________________

Re: Software manual template request

[luigi scarso]

Until now we have two way to document sources:
for *tex file
texmfstart texexec --luatex --modules somefile.tex

for lua
texmfstart texexec --luatex --ctx=x-ldx somefile.lua

(both may need some setup  to work)
Actually this is  the quickest way to have the more accurate dev. documentation,
and I don't think we need something else .

-- 
luigi
it's new .
it's powerful .
it's luatex .
http://www.luatex.org
___________________________________________________________________________________
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  : https://foundry.supelec.fr/projects/contextrev/
wiki     : http://contextgarden.net
___________________________________________________________________________________