On 30 January 2014 21:28, Philipp Janda <siffie...@gmx.net> wrote:
> 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,
They are ASCII-text that need a particular application to render that
are not as ubiquitous as web browsers are and that we can't easily
reuse in both offline and online documentation without some
conversion. (And the point you generate HTML pages, why not ship those
anyway. If the point is viewing them in the terminal, just use
lynx/elinks — I occasionally do!).
> 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.
In my experience, poorly.
> 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 ...
To me these two issues:
> there may not be a central starting point like `index.html` for html
> files.
> you cannot follow links within man
...are indicative that man-pages are a poor fit for this type of
documentation [1]. Don't get me wrong, I "live" inside terminals all
day long and use `man` a lot. But they're not the ultimate solution
for every documentation need (for one, they don't scale that well: the
humongous manpage for bash and the labyrinth of zsh manpages [2] are
examples of poor fits). They're great for checking out some
command-line flags for uniq or to see which standards strcasestr
complies with, and I could even see a reasonable use in a manpage for
zile, but I can't see how manpages would be comfortable for
documenting large Lua APIs (you usually have one manpage per function
with the C standard libraries... would one expect to have one manpage
per Lua function?).
Anyway, these are just my personal opinions on documentation. Not
trying to convince you, just trying to make my position understood.
-- Hisham
[1] and in my boxes man is aliased to pinfo, which does it best to
follow links in manpages (otherwise reading the ncurses documentation
would be just unbearable)
[2] there's fortunately `man zshall`, but it just reduces the zsh
labyrinth problem to a worsened version of the `man bash` problem
------------------------------------------------------------------------------
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
