doc updates: escaping @{}

docs/doc.md

@@ -193,24 +193,24 @@ What applies to functions also applies to any module-level item like tables. New
 
 If a reference is not found within the project, LDoc checks to see if it is a reference to a Lua standard function or table, and links to the online Lua manual. So references like 'table.concat' are handled sensibly.
 
-References may be made inline using the `@{ref}` syntax. This may appear anywhere in the text, and is more flexible than @see. In particular, it provides one way to document the type of a parameter or return value when that type has a particular structure:
+References may be made inline using the @\{ref} syntax. This may appear anywhere in the text, and is more flexible than @see. In particular, it provides one way to document the type of a parameter or return value when that type has a particular structure:
 
     ------
     -- extract standard variables.
     -- @param s the string
-    -- @return @{stdvars}
+    -- @return @\{stdvars}
     function extract_std(s) ... end
 
     ------
     -- standard variables.
-    -- Use @{extract_std} to parse a string containing variables,
-    -- and @{pack_std} to make such a string.
+    -- Use @\{extract_std} to parse a string containing variables,
+    -- and @\{pack_std} to make such a string.
     -- @field length
     -- @field duration
     -- @field viscosity
     -- @table stdvars
 
-`@{ref}` is very useful for referencing your API from code samples and readme text.
+@\{ref} is very useful for referencing your API from code samples and readme text.
 
 ## Sections
 
@@ -412,7 +412,7 @@ Thereafter the `docs` directory will contain `index.html` which points to indivi
 
 If your modules use `module(...)` then the module name has to be deduced. If `ldoc` is run from the root of the package, then this deduction does not need any help - e.g. if your package was `foo` then `ldoc foo` will work as expected. If we were actually in the `foo` directory then `ldoc -b .. .` will correctly deduce the module names. Another example would be generating documentation for LuaDoc itself:
 
-   $ ldoc -b .. /path/to/luadoc
+    $ ldoc -b .. /path/to/luadoc
 
 Without the `-b` setting the base of the package to  the _parent_ of the directory, then implicit modules like `luadoc.config` will be incorrectly placed in the global namespace.
 
@@ -526,14 +526,14 @@ Thanks to mitchell's [TextAdept](http://code.google.com/p/textadept/) project, L
 
 The _navigation section_ down the left has several parts:
 
-    # The project name (`project' in the config)
-    # A project description ('description')
-    # ''Contents'' of the current page
-    # ''Modules'' listing all the modules in this project
+  - The project name (`project' in the config)
+  - A project description ('description')
+  - ''Contents'' of the current page
+  - ''Modules'' listing all the modules in this project
 
 Note that `description` will be passed through Markdown, if it has been specified for the project. This gives you an opportunity to make lists of links, etc; any '##' headers will be formatted like the other top-level items on the navigation bar.
 
-'Contents' is automatically generated. It will contain any explicit sections, if they have been used. Otherwise you will get the usual categories: 'Functions' and 'Tables'.
+'Contents' is automatically generated. It will contain any explicit sections, if they have been used. Otherwise you will get the usual categories: 'Functions', 'Tables' and 'Fields'.
 
 'Modules' will appear for any project providing Lua libraries; there may also be a 'Scripts' section if the project contains Lua scripts. For example,  [LuaMacro](http://stevedonovan.github.com/LuaMacro/docs/api.html) has a driver script `luam` in this section. The [builtin](http://stevedonovan.github.com/LuaMacro/docs/modules/macro.builtin.html) module only defines macros, which are defined as a _custom tag type_. ?ref to config.ld for LM
 
@@ -550,7 +550,7 @@ The line in the `config.ld` that enables this is:
 
 That is, all files in the `examples` folder are to be pretty-printed, except for `slow.lua` which is meant to be called from one of the examples. The see-reference to `testu.lua` resolves to 'examples/testu.lua.html'.
 
-Examples may link back to the API documentation, for instance the example `input.lua` has a `@{spawn_process}` inline reference.
+Examples may link back to the API documentation, for instance the example `input.lua` has a @\{spawn_process} inline reference.
 
 Like all good Github projects, Winapi has a `readme.md`:
 
@@ -558,8 +558,7 @@ Like all good Github projects, Winapi has a `readme.md`:
 
 This goes under the 'Topics' global section; the 'Contents' of this document is generated from the second-level (##) headings of the readme.
 
-Readme files are always processed with Markdown, but may also contain `@{}` references back to the documentation and to example files. As with doc comments, a link to a standard Lua function like @{os.execute}` will work as well. Any code sections will be pretty-printed as well.
-
+Readme files are always processed with Markdown, but may also contain @\{} references back to the documentation and to example files. As with doc comments, a link to a standard Lua function like @\{os.execute} will work as well. Any code sections will be pretty-printed as well.
 
 ## Fields allowed in `config.ld`
 

ldoc/markup.lua

@@ -12,7 +12,7 @@ local markup = {}
 
 -- inline <references> use same lookup as @see
 local function resolve_inline_references (ldoc, txt, item, plain)
-   return (txt:gsub('@{([^}]-)}',function (name)
+   local res = (txt:gsub('@{([^}]-)}',function (name)
       local qname,label = utils.splitv(name,'%s*|')
       if not qname then
          qname = name
@@ -35,6 +35,7 @@ local function resolve_inline_references (ldoc, txt, item, plain)
       local res = ('<a href="%s">%s</a>'):format(ldoc.href(ref),label)
       return res
    end))
+   return res
 end
 
 -- for readme text, the idea here is to create module sections at ## so that
@@ -44,6 +45,7 @@ function markup.add_sections(F, txt)
    for line in stringx.lines(txt) do
       local title = line:match '^##[^#]%s*(.+)'
       if title then
+         title = title:gsub('##$','')
          sections[L] = F:add_document_section(title)
       end
       L = L + 1