The decision to implicitly convert more than one successive new lines to <br> tags doesn't seem quite right. If you are using P or another custom macro to separate paragraphs (which is arguably more correct than using plain <br>'s) the generated layout gets corrupted by the unasked-for line breaks:
/**
$(P Paragraph)
$(P Paragraph)
*/
<br><br> after the first paragraph is absolutely unwelcome in the generated HTML.
Of course, you could workaround that by leaving out the extra line break,
but it is really undesirable because then long paragraphs are not visually separated in the source code:
/**
$(P Mess)
$(P Mess 2)
*/
Another example. You might want to visually separate table rows in source code:
/**
$(TABLE
$(TR
$(TD)
$(TD)
)
$(TR
$(TD)
$(TD)
)
)
*/
Is there a way to avoid <br><br> after </tr> in the generated HTML?
Comment #1 by ddparnell — 2008-03-03T06:56:49Z
Yes, there is a trick. It's not nice but it works. Use $(b) at the begining of the 'blank' line and that prevents <BR><BR> being generated.
/**
$(TABLE
$(b)
$(TR
$(TD)
$(TD)
)
$(b)
$(TR
$(TD)
$(TD)
)
$(b)
)
*/
However, I was thinking that it would be good if when a DDoc line only consisted of a single '*' that DDoc could ignore the line totally.
Comment #2 by aziz.koeksal — 2008-03-03T09:00:47Z
Just define the DDOC_BLANKLINE macro to be empty.
Comment #3 by ddparnell — 2008-03-03T10:22:02Z
Except that doesn't actually work ... or at least I can't get it to work.
First I created this test source file ...
// --------
/**
A Foo Routine
*/
void foo()
{}
/**
The Main Routine
$(TABLE
$(TR
$(TD ABC)
$(TD def)
)
$(TR
$(TD QWERTY)
$(TD asdfgh)
)
)
Params:
pArgs = The arguments
*/
void main(char[][] pArgs)
{
}
// ----------
It generated lots of <BR><BR> sequences.
I then placed this at the top of the file...
/**
Macros:
DDOC_BLANKLINE=
*/
That replaced some of the <BR><BR> sequences with "A Foo routine"! Not what I wanted at all.
So then I removed that macro section and placed it into a pure DDoc file ...
Ddoc
DDOC_BLANKLINE=
And compiled it thus ... dmd test.ddoc test.d -D
That did the same as not havivg the macro redefined. I then changed the test.ddoc file to say ...
Ddoc
DDOC_BLANKLINE=(blank)
And now I get some of the <BR><BR> sequences replaced with "(blank)".
Ok, so how should we be doing this????
Comment #4 by samukha — 2008-03-03T11:04:27Z
/**
Macros:
DDOC_BLANKLINE=
*/
and
/**
A Foo Routine
*/
were merged to give DDOC_BLANKLINE=A Foo Routine? :)
With the implicit line breaks, Ddoc is buggy in at least one more aspect.
Consider this example (modified from the Ddoc spec)
/**
Section:
<li> <a href="http://www.digitalmars.com">Digital Mars</a> </li>
<li> <a href="http://www.classicempire.com">Empire</a> </li>
*/
According to the spec, the embedded HTML should "be passed through to the HTML output unchanged", but it is not the case with the above example because of the implicit <br><br>.
Comment #5 by ddparnell — 2008-03-03T11:23:36Z
Yeah, I figured they were being merged. I did find a work around for it though.
/**
Macros:
DDOC_BLANKLINE=
*/
public: // This forces the end of the macro definitions.
With this, the <BR><BR> sequence are removed, except the ones hardcoded in other DDOC_ predefined macros.
Comment #6 by samukha — 2008-03-04T06:19:47Z
After RTFM and getting some advice from the community, I feel like closing this one, if nobody objects.