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