Am 30.01.2014 23:35 schröbte Hisham:
> On 30 January 2014 20:15, Philipp Janda <siffie...@gmx.net> wrote:
>> Am 30.01.2014 16:40 schröbte Hisham:
>>> On 30 January 2014 07:30, Gary V. Vaughan <g...@vaughan.pe> wrote:
>>>> Hi Hisham,
>>>>
>>>> In principle, would you accept a pull request if I did the work (though I
>>>> know the internals of LuaRocks almost not at all, so I might need some
>>>> pointers and a bit of help here and there)?
>>>
>>> And will you maintain it afterwards? (IOW, can I ping you if bug
>>> reports about it come up?)
>>
>> Manpages is still my favorite online documentation format (sadly not
>> many scripting languages since perl use it), so I'd be willing to help
>> with that ...
>
> One good reason is because they are not portable,
Well, man-pages are ascii-text, but I agree that man-pages are mostly
unknown in Windows-world -- probably because they are best used from the
command line or a terminal editor, and Windows only has crappy terminals
and shells.
> another is that other advances have happened since, such as
> extracting docs from source comments
I'm not sure this particular example actually qualifies as an advance,
but there is no reason why you couldn't generate man-pages from source
comments. E.g. perldoc does something similar. With perldoc you can even
access the man-page information for usage/help messages ...
> and support for richer formatting (I've seen way too many
> misformatted ASCII-art tables in manpages).
I write most of my documentation in Markdown so that I can view it in a
terminal. The original Markdown doesn't support tables either. IIRC,
there is a troff package for tables, but I don't know whether it works
for the terminal. Btw., it seems that pandoc can generate man-pages from
Markdown source ...
> But any kind of documentation is better than no documentation at all,
> of course. My point is that as a personal view, I don't wish to
> promote manpages as a preferred way of producing documentation of Lua
> modules.
>
>>> The way to go about it would be to add an optional flag `--man` to
>>> luarocks/path.lua (like we have with `--bin`) and also, for
>>> consistency, to add knowledge about man pages to luarocks/doc.lua
>>> (though I really don't want to spread logic on finding the `man`
>>> binary all over the place, the way we did it for the web browser. Just
>>> assume you can os.execute("man ...") if cfg.is_platform("unix")
>>> returns true).
>>
>> We would also need `--lr-man` (because Lua 5.2 users can't use the eval
>> trick without messing up their Lua 5.1 paths).
>
> Then just make --man a separate code path entirely, to be executed in a
> separate eval. Also, since it is not portable anyway, there's no need
> to add cfg entries about it, etc. I'm still not convinced that LR
> should learn about man pages if we won't really deploy them — it still
> seems a bit half-baked to me. But let's see if we can get this to be
> really minimal.
>
>> I'm not sure about the
>> `luarocks doc` integration, that seems rather complicated ...
>
> I was just thinking that if man/bla.1 exists, then just run something
> like os.execute("man -M "..appropriate_dir.." bla.1") and be done with
> it. My point is that it's weird if a developer is shipping some kind
> of documentation and it is inacessible via `luarocks doc`.
Yes, but usually you don't have only one big man-page for a rock, but
several (e.g. one for each sub-module, or even for each function), and
there may not be a central starting point like `index.html` for html
files. Imagine a rock `Rock` which consists of two modules `Rock.one`
and `Rock.two`. What should `luarocks doc Rock` display? You could
provide a general Rock.3 man-page which provides an overview, but to
access the details you would still need to set the MANPATH and execute
man manually (i.e. you cannot follow links within man). We could make
`luarocks doc Rock.one` (or even `luarocks doc Rock.one.func`) work, but
this would require a completely separate mechanism for scanning rocks
directories for matching man pages ...
>
> -- Hisham
>
Philipp
------------------------------------------------------------------------------
WatchGuard Dimension instantly turns raw network data into actionable
security intelligence. It gives you real-time visual feedback on key
security issues and trends. Skip the complicated setup - simply import
a virtual appliance and go from zero to informed in seconds.
http://pubads.g.doubleclick.net/gampad/clk?id=123612991&iu=/4140/ostg.clktrk
_______________________________________________
Luarocks-developers mailing list
Luarocks-developers@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/luarocks-developers
