Am 31.01.2014 02:06 schröbte Hisham: > > 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.
If you want online documentation (as in WWW), then there's no way around HTML (maybe PDF?, Firefox has a nice PDF renderer built-in). > (And the point you generate HTML pages, why not ship those anyway. This is not an xor situation, you obviously can ship multiple different formats. The reason I don't ship generated HTML files for my rocks is because they need to be generated, and that's difficult to do portably from within luarocks (I currently use `markdown.lua` plus some post processing via `xsltproc`). I could generate HTML files and upload a custom package somewhere, but building directly from a github repository is really convenient. > If the point is viewing them in the terminal, just use lynx/elinks — > I occasionally do!). Not the same, and I think this has more to do with organization than with format. E.g. if I want to know the details about e.g. `fprintf` I call `man fprintf` (or hit shift-K in vim). How would I get the same information in lynx/elinks? There probably is some libc documentation on my computer somewhere, but `man` is just faster. `luarocks doc` is a step in the right direction, though. I also like Dirk Laurie's `ihelp`, and I'm working on documenting Lua's standard library for an interactive help system based on docstrings (progress is slow, though). > > > 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). The `bash` manpage *is* huge, no argument there, but it is basically documenting a whole programming language. And what is the alternative? One huge HTML page? Multiple interlinked HTML pages, so that you can't even use a browser search? Google? Having a central starting point as an overview is nice. Having to go through multiple links until you find the information you seek is not. > 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?). I guess so. My personal limit is about 5 (closely related) functions per man-page, or maybe one simple module. I see man-pages as an LDoc-like online reference with direct access to the details. > > Anyway, these are just my personal opinions on documentation. Not > trying to convince you, just trying to make my position understood. Same here. I just said that I like man-pages and I would help maintain man-page handling in LuaRocks in case Gary decides to work on it ... > > -- 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
