www.digitalmars.com         C & C++   DMDScript  

digitalmars.D.bugs - [Issue 1889] New: Ddoc and <br>

reply d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=1889

           Summary: Ddoc and <br>
           Product: D
           Version: 1.027
          Platform: PC
        OS/Version: Windows
            Status: NEW
          Severity: major
          Priority: P2
         Component: DMD
        AssignedTo: bugzilla digitalmars.com
        ReportedBy: samukha voliacable.com


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?


--
Mar 03 2008
next sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=1889






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.


--
Mar 03 2008
prev sibling next sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=1889






Just define the DDOC_BLANKLINE macro to be empty.


--
Mar 03 2008
prev sibling next sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=1889






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????


--
Mar 03 2008
prev sibling next sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=1889






/**
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>.


--
Mar 03 2008
prev sibling next sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=1889






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.


--
Mar 03 2008
prev sibling next sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=1889






After RTFM and getting some advice from the community, I feel like closing this
one, if nobody objects.


--
Mar 04 2008
prev sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=1889


samukha voliacable.com changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
             Status|NEW                         |RESOLVED
         Resolution|                            |INVALID




--
Mar 04 2008