* Does asciidoc allow to show code snips marked in an external source file? For example, to show example code snips in Quickbook using [import <file-name>] and then [abc], where //[abc ... //] are used as markers in file-name.
This is the QuickBook feature I would miss. I've used that heavily to ensure that the code embedded in the documentation is code that actually builds and runs, without having to remember to (re-)paste updates into the document source.
I too have been playing with radically different methods of generating documentation for Outcome v2, seeing as people panned the v1 Outcome documentation. This is bleeding edge stuff i.e. it currently segfaults a lot, but it is getting there. It uses Hugo to compile the Markdown source files into HTML via a Travis per-commit job. Standardese may - once Jonathan fixes the bugs - generate the reference API docs in Markdown from doxygen marked up C++ source files using libclang. If we can get it working, it'll be a whole new age of "easy" for writing docs for complex C++ codebases, and moreover one which finally can parse the worst possible C++ metaprogramming without blinking because anything clang can parse can be documented. You literally run just two build tools, both easily executed from Travis, and push the changes to gh-pages on Github. Changing documentation is as easy as modifying the Markdown source or the doxygen format comment section in the relevant header, git commit and git push. Hugo generates the syntax highlighting, the wiki linking, the search index and everything else. Oh, and it looks pretty, even on a mobile phone. You can swipe the tutorial left and right for example. You can see our joint efforts so far for Outcome v2 at https://ned14.github.io/outcome/. You can thank Andrzej for the tutorial written so far, it's all him. Niall -- ned Productions Limited Consulting http://www.nedproductions.biz/ http://ie.linkedin.com/in/nialldouglas/