Worst Phobos documentation evar!

[H. S. Teoh via Digitalmars-d]

On Mon, Dec 29, 2014 at 05:19:27PM -0800, Walter Bright via Digitalmars-d wrote:
> On 12/29/2014 4:45 PM, H. S. Teoh via Digitalmars-d wrote:
[...]
> >>But at least you can make it work with LaTeX. Whatcha gonna do with
> >>Markdown?
> >Again, I wasn't defending Markdown.
> 
> Then I'm a bit lost on what the point of complaining about Ddoc is.
> Are you arguing that Ddoc should implement LaTeX?

No, I'm saying that ddoc fails to be either (1) a human-readable source
that can also be converted into a nicer format like HTML or LaTeX, or
(2) a powerful-enough markup language that encompasses all necessary
functionality that HTML/LaTeX/etc. encompass. Apparently point (2) fails
by design, since you & Andrei repeatedly claim that ddoc should not be
"too powerful". Point (1) fails because no matter what you do, you still
have to insert markup *somewhere*. IOW, it's neither nice enough to be
human-readable, nor powerful enough to justify the reduction in
readability.


> >The only way to get it right is to turn your ddoc comments into tag
> >soup. Are you seriously suggesting that we have to write ddoc tag
> >soup while coding? Or that we first write in plain text then go back
> >afterwards and wrap every paragraph in $(P ...) macros? The only
> >reason zero source code changes were required, was because the ddoc
> >comments were already written with the requisite tag soup to begin
> >with. Which is OK, if that's the "correct" way to use ddoc... but in
> >that case, the page on dlang.org that describes ddoc should be
> >revised to not give the false impression that you can just write
> >documentation comments in plain text format and expect to get nice
> >output from it.
> 
> I think this is an unfair critique. The blank lines separating
> paragraphs work fine.

They certainly do not. Consider this:

	First section heading:
		Passing in a forward range that doesn't have .length may
		trigger some unexpected side effects.

		Some other description goes here.

	Second section heading:
		More descriptions follow here.

The correct XHTML markup would be something like this:

	<h2>First section heading:</h2>

	<p>Passing in a forward range that doesn't have .length may
	trigger some unexpected side effects.</p>

	<p>Some other description goes here.</p>

	<h2>Second section heading</h2>

	<p>More descriptions follow here.</p>

Now consider the structure of the input, as understood by ddoc:

	$(HEADING First section heading:)
	Passing in a forward range ... side effects.
	$(BLANKLINE)
	Some other description goes here.
	$(HEADING Second section heading:)
	More descriptions follow here.

How do you get from this structure, to the structure of the XHTML markup
above? You can't. You *can* hack it so that <p> is inserted by
$(HEADING), and $(BLANKLINE) prepends </p>, and $(BLANKLINE) expands to
</p><p>, but this will fail at the transition to the second heading: the
second paragraph won't be closed. Unless you also prepend </p> in
$(HEADING), but then the first heading will acquire an extraneous </p>,
which breaks the markup.

Things get worse if you now try to insert code blocks between
paragraphs, or paragraphs within quoted blocks. Basically, the structure
of $(BLANKLINE) does not perfectly align with tag boundaries, therefore
no hack will cover all possible cases. The XHTML output will be
malformed.

Basically, $(BLANKLINE) only works if you use <br/> for paragraph
breaks, but that screws up CSS styling when you actually want
semantically-tagged paragraphs.

Using blank lines to separate paragraphs would be fine, *if* ddoc
processes them internally and wraps paragraphs in $(P...) automatically
instead of inserting $(BLANKLINE). However, currently it doesn't. And I
am loathe to change this because the PR will inevitably get rejected,
since it will break every ddoc macro set that relies on $(BLANKLINE).


> Ddoc is not intended to be LaTeX. That it can't do everything a
> professional typesetting language can is not remarkable, no other
> markup language can, either.

The problem with this, is that ddoc is imposed upon all D users.  It
tries to be readable, but fails to be beyond the most trivial of cases.
Things like embedded code blocks and section headings have special
meaning, and have a nice human-readable input syntax, but other common
constructs such as lists and tables require ugly macro syntax. I'd
rather that macro syntax is either used *everywhere* (make it a
full-fledged markup language) or nowhere (make it a fully human-readable
language), but what we have now is a halfway job.

And then, having included macros, which are deemed necessary, it doesn't
go far enough either -- certain things (like autoindexing symbols in a
module for making a table of contents, for example) aren't possible
without lots of manual work and duplication. There are no capabilities
for working with the text itself -- like capitalization so that you can
use macros for extracting and placing text snippets in different places,
inserting escape sequences for sensitive characters in the target
format, extracting symbols to make a table of contents, etc.. This is
apparently a deliberate design choice, which makes it feel like we're
dangling the enticing capability to be a powerful documentation system,
yet we withhold actual text-processing capabilities so that you either
have to live with inferior output, or implement custom post-processing
tools. Again, it feels like another halfway job, it's neither here nor
there.

I'm not saying that the macro system sucks -- it's actually quite
elegantly designed as far as macro languages go -- but the problem is
that the ddoc system as a whole shies away from what it is. It pretends
to be human-readable when it is not, and on the other hand it tries to
be a powerful text macro system yet shies away from actual
text-processing capabilities. I wish we would stop trying to be all
things to everyone, and settle one way or the other. Either we cater to
the human-readable-input crowd and make it fully human readable with
markdown-like syntax (or whatever other syntax you care to design), or
we go all-out with the macro system and endow it with the full
text-processing capabilities that it currently lacks. Right now we're
stuck in between, and do neither very well.


T

-- 
MAS = Mana Ada Sistem?