[ANN] LDoc 1.3.8

[steve donovan <steve.j.donovan@...>]

Hi all,

LDoc[1] is a (mostly) LuaDoc-compatible Lua documentation tool with
extended features:

  * also works with C Lua extension code
  * type annotations: @tparam string name, or even @string name.
  * optional arguments can be indicated with the [opt] modifier;
optional-with-default values is done with [opt=default]
  * you may use Markdown to process docstrings
   (markdown.lua,   lua-discount and luamark are supported, with
graceful degradation)
  * narrative documentation like readmes and so forth may be included
    (this is how the Penlight manual [2] is constructed)
  * code blocks are prettified, and Github-style code fence blocks
(```lua) are supported.
    You may choose to use lua-lxsh[3] as a prettifier, which also
supports 'c' and 'sh'
  * prettified code examples can be included directly in a project.

This version has a new feature which is useful for C developers; a
module can be spread across several files, with the @submodule tag;
the only requirement is that the 'master' module appears first in the
file list.

Thanks to discussions with Tomas, there's now another way to specify
those tricky arguments which are tables:

-------
-- A function with subfield arguments.
-- @param s string
-- @param opts multibyte encoding options
-- @param opts.charset string
-- @param opts.strict bool
-- @param verbose bool
-- @return its length
function with_options (s,opts,verbose)
end

For those who hate @tag soup, you can always choose to go tag-free
(like the bundled docs for the Lua standard libraries) and adjust the
presentation accordingly.

Or, with colon=true or -C, use colons:

-------
--- Function summary.
-- Function description.
-- string: name
-- int: age
......

The manual is here [4]. The best guide is the examples in tests,
particularly tests/styles, which is a gallery of supported styles.

The templates and stylesheets are practically a direct crib from the
old LuaDoc, due to my difficulties in making things look good. If you
feel creative you can specify your own style sheets, as Nils Nordman
as done here: http://nilnor.github.com/textui/docs/

I'd love to include some more _modern_ layouts, so here I must appeal
to people who have taste for contributions.

LDoc is available as a zip [5]. tagged download (see 'Tags') and
through LuaRocks as 'ldoc'. There is a makefile for installation, but
a manual install simply involves unzipping the works in a directory
and providing a symlink or batch file to run the 'ldoc.lua' script in
that directory. (Penlight is the only dependency)

There have been a _lot_ of contributers and testers, so I've never
felt lonely on this project!  The enormous variety of Lua coding
styles has made this a very interesting challenge.

note:
(1) if you're using an older version of LuaRocks (like that which
comes with Debian/Ubuntu) then the executable is 'ldoc.lua'. Symlink
your way to sanity.
(2) Tomas has just pointed out a late-breaking issue that may occur
when upgrading; if your documents still say 'generated by 1.2' then
the problem can be solved by cleaning out the old templates in
/tmp/ldoc.

steve d.

[1] https://github.com/stevedonovan/LDoc
[2] http://stevedonovan.github.com/Penlight/api/topics/01-introduction.md.html
[3] https://github.com/xolox/lua-lxsh (by Peter Odding)
[4] http://stevedonovan.github.com/ldoc
[5] http://stevedonovan.github.com/files/ldoc-1.3.8.zip