tech-userlevel archive

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index][Old Index]

Re: Documentation of Lua modules



Am 10.10.13 09:31, schrieb Matt Thomas:
> 
> On Oct 10, 2013, at 12:13 AM, Marc Balmer <marc%msys.ch@localhost> wrote:
> 
>> Lua modules provide functionality to Lua programs, e.g. accessing SQLite
>> databases or GPIO pins from Lua.  These modules should of course be
>> documented, what their purpose is, and the functions they provide.
>>
>> Note that these are not C library functions, so section 3 of the manual
>> is inappropriate, plus there are name clashes with existing manual pages
>> to be expected (e.g. gpio is in section 4, but there is also a Lua
>> module named gpio).
>>
>> After discusssing with several developers and especially after a few
>> email exchanges with Thomas Klausner, I propose the following scheme:
>>
>> - A new manual section for Lua documentation is created, 3l.  The
>> physical directory in the source tree would then be man3l.  To lookup a
>> manpage, we use '3l' and 'lua' in man.conf.  3l will be searched after
>> section 3, before section 4.  'lua' is just an alias for '3l'.
>>
>> - Modules are described in man pages with the same name as the module
>> name, e.g. the gpio module will be documented in gpio(3l).
>>
>> - Functions within modules will be documented in a man page with the
>> function name prefixed by the module name, e.g. the open function in the
>> gpio module will be documented in gpio.open(3l)
>>
>> Thomas Klausner is fine with this, I am posting it here in case someone
>> has a better idea.
>>
>> Also note that this scheme is consistent with e.g. Perl that uses
>> section 6p, afaict.
> 
> I'd rather have it use 3lua (man3lua).  Other than that, I'm fine with it.

I chose 3l for brevity and consistency.  Could you live with '3lua'
being an alias in man.conf for '3l'?

I'd be happy to settle for a "solution" soon, so that I can go on with
the actual documentation.




Home | Main Index | Thread Index | Old Index