On 12/31/13 4:26 AM, Jacob Carlborg wrote:
On 2013-12-31 01:05, Sönke Ludwig wrote:
Also, the official first four goals of DDOC are:
1. It looks good as embedded documentation, not just after it is
extracted and processed.
It certainly does not. Just have a look at the top of std.algorithm or
std.uni. Hundreds of lines of Ddoc madness.
That's an exaggeration. The top of std.algorithm produces complex output
(two tables). The rest of the documentation is nice and legible.
2. It's easy and natural to write, i.e. minimal reliance on <tags> and
other clumsy forms one would never see in a finished document.
Fails again. As soon as you need something more advanced than the
standard sections you need to use macros. The macros are just as tags,
just with a different syntax and name.
As one who's written both, I can testify this isn't true. Ddoc macros
need to be mentioned once and then the closing paren completes them.
Additionally, they can expand to arbitrarily complex output. In
contrast, tags need to be mentioned twice (an often-mentioned issue with
writing HTML by hand), are syntactically heavier, and therefore litter
the text a lot more.
3. It does not repeat information that the compiler already knows from
parsing the code.
You sure need to do if you want good documentation. Take a look at
std.algorithm, it has over 300 lines of Ddoc code to create a symbol
table that Ddoc should be able to automatically generate.
No. There are two tables there. One is a categorization of algorithms,
which is human-made. There are several solutions to materializing that
table but they all would require the intervention of a human being. I
figured std.algorithm adds new algorithms rarely enough to allow myself
a solution that requires manual intervention.
The second table is a "cheat sheet" with human-produced short
descriptions for each function. Those short descriptions wouldn't fit
well with the longer descriptions.
4. It doesn't rely on embedded HTML, as such will impede extraction
and formatting for other purposes.
As far as I know this isn't very useful. For the other formats we use,
like PDF, it uses the HTML output as a base.
Again no. You are misinformed. The PDF manual is generated via LaTeX
from the same ddoc sources as the HTML pages.
Andrei
