On Wed, Jan 01, 2014 at 06:41:50PM -0800, Andrei Alexandrescu wrote: > On 1/1/14 4:56 AM, Jacob Carlborg wrote: [...] > >I'm considering it to be a sort of tag, just with a different syntax. > >Who said tags need to have an end tag. A less verbose a minimal > >reliance on tags would be Markdown or similar. Creating a list in > >Markdown is simple as: > > > >* this > >* is > >* a > >* list > >* in Markdown > > I prefer ddoc to markdown for its flexibility. Ddoc is an almost > pure macro expansion system with minimal syntax. Markdown defines a > bunch of syntax but has (last time I looked) is weak on macro > capability.
Well, ddoc was designed to be a macro system, so from that POV, it's pretty good at what it was intended to do. Whether it's the best system for *generating documentation*, though, is a matter of opinion. Markdown has the advantage of having very close visual appearance in the input as compared to the output -- a stated goal of ddoc, but obviously the unified macro syntax was a higher priority in ddoc's case. For example, using `backticks` to write code snippets is definitely more readable than writing $(D backticks), among many other things. But that does introduce more syntax, which makes parsing more involved and also requires learning more syntax. So, it's a trade-off. > Case in point: markdown lists will be styled one way. With DDoc > macros one can define any style of lists needed. (We've defined > BOOKTABLE in addition to a couple of other TABLEs, which works > beautifully in HTML and LaTeX; not sure how can be done in Markdown. Styling is an orthogonal issue. Markdown was designed to translate to HTML, so you'd just write CSS stylesheets to customize the output. Ddoc, OTOH, was designed to be a generic macro system, so obviously it's better at doing macro-based stuff. > >If there's a specific macro that would indicate a category then it > >would be easy to generate a table like that. > > > >/// $(CATEGORY searching) > >void foo () > > The issue is with writing text out of order, something DDoc is not > very apt at. Would be nice to improve on that (we do some of it with > javascript). [...] The limitation of macro systems is that, fundamentally speaking, no semantics are assigned to macros. A macro is just an arbitrary name that gets recursively substituted with some pre-specified pattern. The macro engine doesn't know what any of the macros "mean", and therefore has no concept of things like cross-referencing, categorization, etc., which are all higher-level, logical concepts, that are required in order to move data around. There are, of course, ways of simulating this with macros, such as with a global top-level macro that takes an arbitrary number of arguments and can permute them at will, but this is ultimately just a hack. Macro systems simply don't provide enough expressive power to build abstractions like "this block of text is a `declaration` with `identifier` as key, so add `identifier` to the index structure in the output". Postprocessing is the only way to reliably add this kind of semantics to it. But postprocessing also removes some of the advantage of ddoc: if you translate everything down to HTML tags, the postprocessor will have to reparse the HTML and resynthesize information on where sections begin/end, what constitutes a declaration, etc., which may not be reliable. So now you have to use an intermediate format (like docbook) that still captures some of the original structure, so that the postprocessor can reliably recover the original document structure from it. But then, you might as well just write in the intermediate format to begin with, instead of using ddoc. So while I do agree that ddoc is pretty good at what it does -- expanding macros -- I'm still on the fence as to whether that's the best approach to documentation generation. T -- Sometimes the best solution to morale problems is just to fire all of the unhappy people. -- despair.com
