Bumped version to 1.4.3; doc updates; C lexer ignores strings (which it handles badly)

changes.md

@@ -1,3 +1,25 @@
+## Version 1.4.3
+
+### Features
+
+  * @include tag for including Markdown documentation file directly into module docstring
+  * `prettify_files` makes per-item links to prettified source.
+  * link targets rendered in bright yellow to make referenced functions more obvious
+  * add update time to footer of page
+  * better C support: `global_lookup=true` - invoked when `parse_extra={C=true}`
+  * `kind_names` can override names used in sidebar
+  
+### Fixes
+
+  * `all=true` in `config.ld` did not work.
+  * `dont_escape_underscore` logic fixed: do not use in prettified code blocks
+  * check that `ldoc` config exists before checking field values
+  * annotation rendering fixed
+  * summary not dropped when using `type` sections
+  * directory as argument case was broken
+  * parameter names which were List methods causing mayhem
+  * files are processed in fixed order across platforms
+
 ## Version 1.4.2
 
 ### Features

doc/doc.md

@@ -143,12 +143,14 @@ This is a simple example of a documented function:
 You can also give the function name itself as an explicit tag,
 which is especially useful when documenting a Lua api exported by C code:
 
+```C
 /// A C function which is exported to Lua with another name,
 // because the ways of C can be mysterious!
 // @function our_nice_function
 int _some_function_for_lua(lua_State* l) {
     ....
 }
+```
 
 The tags basically add all the detail that cannot be derived from the source code
 automatically.
@@ -189,7 +191,6 @@ function. For Lua, there can also be multiple 'return' tags
     end
 
     ...
-Of course there is also the 'module' tag which you have already seen.
 
 #### Tables and constant values (fields)
 
@@ -216,7 +217,8 @@ This can get tedious, so LDoc will attempt to extract table documentation from c
 
 The rule followed here is `NAME = <table-constructor>`. If LDoc can't work out the name and
 type from the following code, then a warning will be issued, pointing to the file and
-location.
+location.  Only single-level tables are currently supported, and the fields must be valid
+identifiers.
 
 Another kind of module-level type is 'field', such as follows:
 
@@ -239,9 +241,8 @@ When the code analysis would lead to the wrong type, you can always be explicit.
         ...
     end
 
-As mentioned before, this is often especially useful in C where things
-may look different in the C code than they will in the final Lua api which
-you want to document.
+This is especially useful in C where the function declarations
+are different from final Lua api which you are documenting.
 
 ### Doing modules the Lua 5.1 way
 
@@ -293,7 +294,8 @@ explicit assignment to a variable:
 ### Local functions
 
 Apart from exported functions, a module usually contains local functions. By default, LDoc
-does not include these in the documentation, but they can be enabled using the `--all` flag.
+does not include these in the documentation, but they can be enabled using the `--all` flag,
+or `all=true` in `config.ld`.
 They can be documented just like 'public' functions:
 
     --- it's clear that boo is local from context.
@@ -406,8 +408,12 @@ type of a parameter or return value when that type has a particular structure:
 The link text can be changed from the default by the extended syntax `@{\ref|text}.
 
 You can also put references in backticks, like `\`stdvars\``. This is commonly used in
-Markdown to indicate code, so it comes naturally when writing documents. It is controlled by
-the configuration variable `backtick_references` or the `backtick` format;
+Markdown to indicate code, so it comes naturally when writing documents. The difference
+is that the backticked expression does not have to be a reference and then will appear
+in code style; with @ references you will get a warning for unrecognized symbols
+and the result will be rendered as '???'.
+
+It is controlled by the configuration variable `backtick_references` or the `backtick` format;
 the default is `true` if you use Markdown in your project, but can be specified explicitly
 in `config.ld`.
 
@@ -944,6 +950,9 @@ control what the template will generate. Setting `one=true` in your configuratio
 will give a _one-column_ layout, which can be easier to use as a programming reference.  You
 can suppress the contents summary with `no_summary`.
 
+If you don't like the usual top-level names, like 'Module' and 'Topics', you can override these
+with `kind_names` in `config.ld`. For instance, in Penlight I use `kind_names={topic='Manual',module='Libraries'}`
+
 ## Customizing the Page
 
 A basic customization is to override the default UTF-8 encoding using `charset`. For instance,
@@ -1012,6 +1021,9 @@ and also in code if they're enclosed in backticks. Lua and C are known languages
 can be used (available from LuaRocks) if you want something more powerful. `pretty='lxsh'` will
 cause `lxsh` to be used, if available.
 
+Sometimes the best examples you have are your source files. `prettify_files=true` will prettify
+all sources, and generate per-function links to the source.
+
 ##  Readme files
 
 Like all good Github projects, Winapi has a `readme.md`:
@@ -1116,6 +1128,7 @@ As an extension, you're allowed to use **@param** tags in table definitions. Thi
 possible to use type aliases like **@string** to describe fields, since they will expand to
 'param'.
 
+
 Another modifier understood by LDoc is `opt`. For instance,
 
     ---- testing [opt]
@@ -1123,12 +1136,28 @@ Another modifier understood by LDoc is `opt`. For instance,
     -- @param[opt] two
     -- @param three
     -- @param[opt] four
-    function two (one,two,three,four)
+    function fun (one,two,three,four)
     end
-    ----> displayed as: two (one [, two], three [, four])
+    ----> displayed as: fun (one [, two], three [, four])
     
-This modifier can also be used with type aliases. If a value is given for `opt`
-then LDoc can present this as the default value for this optional argument.
+A more typical Lua API would have a chain of optional arguments, like so:
+
+    ---- a chain of options
+    -- @param one
+    -- @param[opt] two
+    -- @param[optchain] three
+    -- @param[optchain] four
+    function fun (one,two,three,four)
+    end
+    ----> displayed as: fun (one [, two [, three [, four]]])
+    
+This is a bit tedious to type, so the rule is that a series of 'opt' modifiers will be interpreted
+as 'opt','optchain'.... .   If you want to be explicit, then do `convert_opt=true` in your
+`config.ld`.
+
+If a value is given for `opt`then LDoc can present this as the default value for this optional argument.
+
+This modifier can also be used with typed param aliases.
 
     --- a function with typed args.
     -- If the Lua function has varargs, then
@@ -1142,7 +1171,6 @@ then LDoc can present this as the default value for this optional argument.
     end
     ----> displayed as: one (name, age [, calender='gregorian' [, offset=0]])
 
-
 (See @{four.lua}, rendered [here](http://stevedonovan.github.io/ldoc/examples/four))
 
 An experimental feature in 1.4 allows different 'return groups' to be defined. There may be

ldoc/html/ldoc_ltp.lua

@@ -289,7 +289,7 @@ return [==[
 </div> <!-- id="content" -->
 </div> <!-- id="main" -->
 <div id="about">
-<i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.2</a></i>
+<i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.3</a></i>
 <i style="float:right;">Last updated $(ldoc.updatetime) </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->

ldoc/lexer.lua

@@ -350,9 +350,9 @@ function lexer.cpp(s,filter,options)
             {IDEN,cpp_vdump},
             {NUMBER4,ndump},
             {NUMBER5,ndump},
-            {STRING3,sdump},
-            {STRING1,chdump},
-            {STRING2,sdump},
+          --  {STRING3,sdump},
+          --  {STRING1,chdump},
+          --  {STRING2,sdump},
             {'^//.-\n',cdump},
             {'^/%*.-%*/',cdump},
             {'^==',tdump},