On Jan 31, 2014, at 12:28 PM, 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, 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. Right, and for the most part, I'm currently interested in shipping section 1 man pages for command line utilities, so the Windows folks will either be using cygwin or similar to get a command-line that makes using my command line rocks (specl, zile, etc) worthwhile, and thus have a man utility, or else they won't care about running a command line utility at all, and so the man pages will not be needed :) >> 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 ... In the fullness of time, I'd be very happy to have section 3 manual pages generated from ldoc comments as a supplement to the HTML docs. I basically *never* search documentation in a browser it's too slow and too much of a context switch. Currently I use the nice `ldoc -m string.find` style to lookup method arguments quickly, but `man string.find` would be closer to how I look things up for shell and tcl and C programming. But for now, section 1 support would be a nice step forward for me. >> 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 ... I use markdown for almost everything that's not source code these days too. GNU's groff comes with grog which can often intuit the need to funnel an *roff source through tbl for nice display of tables. Very occasionally, I have to manually pipe pages through tbl, but grog is a 95% solution. > 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. Right, just 1-5 closely related functions per man-page is best for section 2 and 3 pages. But that's another step beyond what I'm angling for at the moment. It affects section 1 pages too though. Zile ships zmacs.1 and zz.1, and soon to be others. There is definitely no 1-to-1 mapping. Cheers, -- Gary V. Vaughan (gary AT vaughan DOT pe)
signature.asc
Description: Message signed with OpenPGP using GPGMail
------------------------------------------------------------------------------ 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
