www.digitalmars.com         C & C++   DMDScript  

digitalmars.D.learn - DDoc richness

reply Derek Parnell <derek psych.ward> writes:
I've tried to convert some of my existing embedded documentation to the new
DDoc format. I've found out so far that DDoc is not rich enough to do a
good job. It is missing some things to make life easier.

** It has no support for lists. I find that lists are a common
documentation construct. 

** It has no support for highlighting user-defined words, and I'm not
talking about program identifiers etc... I'm talking about arbitrary words
and phrases that the author wants highlighted.

** It has no support for multiple output files. Currently, one HTML file is
generated for one source file.

** It has no support for automatic index generation. Various types of
source identifiers (eg. functions and global variables) plus author defined
bookmarks would be useful to be indexed.

** It has no support for an automatically generated Table of Contents.

** The generated HTML should use <hr/> and <br/> instead of <hr> and <br>
respectively.

** The generated HTML uses <dl> without any <dt> and <dd> entries. Why is
<dl> being used?

** Instead of using unadorned <p> </p> blocks for sections, you could
generated style references so people could utilize style sheets. Eg. 

   <p><span class=ddoc_section>date:</span> Sep 20, 2005 </p>

and the style sheet could then define ...

   span.ddoc_section { font-weight: bold }


-- 
Derek
(skype: derek.j.parnell)
Melbourne, Australia
20/09/2005 3:41:56 PM
Sep 19 2005
next sibling parent reply Stewart Gordon <smjg_1998 yahoo.com> writes:
Derek Parnell wrote:
<snip>

 ** The generated HTML should use <hr/> and <br/> instead of <hr> and <br>
 respectively.


Wrong.

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
    "http://www.w3.org/TR/html4/loose.dtd">


 ** The generated HTML uses <dl> without any <dt> and <dd> entries. Why is
 <dl> being used?
 
 ** Instead of using unadorned <p> </p> blocks for sections, you could
 generated style references so people could utilize style sheets. Eg. 


<snip>

Indeed, it should avoid using presentational markup altogether.  Just 
look at the amount of formatting it hard-codes, which would be easy to 
make flexible by using CSS instead!

And don't forget: It should generate valid HTML.

Stewart.

-- 
-----BEGIN GEEK CODE BLOCK-----
Version: 3.1
GCS/M d- s:- C++  a->--- UB  P+ L E  W++  N+++ o K-  w++  O? M V? PS- 
PE- Y? PGP- t- 5? X? R b DI? D G e++>++++ h-- r-- !y
------END GEEK CODE BLOCK------

My e-mail is valid but not my primary mailbox.  Please keep replies on 
the 'group where everyone may benefit.
Sep 20 2005
next sibling parent Georg Wrede <georg.wrede nospam.org> writes:
Stewart Gordon wrote:

 Derek Parnell wrote:
 <snip>
 

 ** The generated HTML should use <hr/> and <br/> instead of <hr> and <br>
 respectively.


 
 
 Wrong.
 
 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
    "http://www.w3.org/TR/html4/loose.dtd">
 

 ** The generated HTML uses <dl> without any <dt> and <dd> entries. Why is
 <dl> being used?

 ** Instead of using unadorned <p> </p> blocks for sections, you could
 generated style references so people could utilize style sheets. Eg. 


 
 <snip>
 
 Indeed, it should avoid using presentational markup altogether.  Just 
 look at the amount of formatting it hard-codes, which would be easy to 
 make flexible by using CSS instead!
 
 And don't forget: It should generate valid HTML.
 
 Stewart.
 



True enough!

But then again, do we want Walter to get a degree in HTML, or to go back 
to fixing the rest of the compiler?

In other words, let's do the above fixes and then send him the diffs?
Sep 20 2005
prev sibling parent reply Derek Parnell <derek psych.ward> writes:
On Tue, 20 Sep 2005 10:43:16 +0100, Stewart Gordon wrote:


 Derek Parnell wrote:
 <snip>

 ** The generated HTML should use <hr/> and <br/> instead of <hr> and <br>
 respectively.


 
 Wrong.
 
 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
     "http://www.w3.org/TR/html4/loose.dtd">
 


Thank you for your brevity. However, due to my shortcomings in
understanding the rationale for your response, I'm wondering if I could beg
an expanded version from you.

I am hampered by my limited ability to fully understand the DTD specified.
It has, as does the strict DTD, 

  <!ELEMENT BR - O EMPTY                 -- forced line break -->

which means that the BR tag must be an empty element and thus should take
the form <BR/> rather than <BR>...</BR> .  I don't know the meaning of the
"- O" in the definition, but I guess by your response that it indicates
that the "/" to end the tag is optional.

But to confirm, are you saying that such EMPTY elements are allowed to have
optional endings such that <BR> is equivalent to <BR/> ? Even if this is
so, I would recommend that the longer option is used as it appears more
expressive and self-contained. By this I mean that anyone seeing <BR/>
knows straight away that there is not meant to be a matching </BR> tag,
without having to know the semantics of the BR tag.

-- 
Derek Parnell
Melbourne, Australia
20/09/2005 11:45:27 PM
Sep 20 2005
parent reply Stewart Gordon <smjg_1998 yahoo.com> writes:
Derek Parnell wrote:
<snip>

 I am hampered by my limited ability to fully understand the DTD specified.
 It has, as does the strict DTD, 
 
   <!ELEMENT BR - O EMPTY                 -- forced line break -->
 
 which means that the BR tag must be an empty element and thus should take
 the form <BR/> rather than <BR>...</BR> . 


<br> or <BR>.  Or if you like, <Br> or <bR>.  Not <BR/>.  In HTML, as 
opposed to XHTML, there's no such thing as /> at the end of a tag.

Taking a quick look, there appear to be four kinds of elements:

- -         must have start and end tags (e.g. H1)
O O         exists implicitly (e.g. BODY)
- O         end tag optional (e.g. P)
- O EMPTY   empty element - end tag forbidden (e.g. BR)


The DTD for XHTML 1.0 Strict, OTOH, gives

<!ELEMENT br EMPTY>   <!-- forced line break -->
<!ATTLIST br
   %coreattrs;
   >

Here, the EMPTY tag stipulates that there must be nothing inside the 
element, but it's up to you whether you write it as <br /> or <br></br>. 
  But remember that X(HT)ML is case-sensitive.

<snip>

 But to confirm, are you saying that such EMPTY elements are allowed to have
 optional endings such that <BR> is equivalent to <BR/> ? Even if this is
 so, I would recommend that the longer option is used as it appears more
 expressive and self-contained. By this I mean that anyone seeing <BR/>
 knows straight away that there is not meant to be a matching </BR> tag,
 without having to know the semantics of the BR tag.


No, because writing <BR/> would make it invalid HTML.

Stewart.

-- 
-----BEGIN GEEK CODE BLOCK-----
Version: 3.1
GCS/M d- s:- C++  a->--- UB  P+ L E  W++  N+++ o K-  w++  O? M V? PS- 
PE- Y? PGP- t- 5? X? R b DI? D G e++>++++ h-- r-- !y
------END GEEK CODE BLOCK------

My e-mail is valid but not my primary mailbox.  Please keep replies on 
the 'group where everyone may benefit.
Sep 20 2005
next sibling parent =?utf-8?B?RGF3aWQgQ2nEmcW8YXJraWV3aWN6?= <araelx gmail.com> writes:
On Tue, 20 Sep 2005 17:39:57 +0200, Stewart Gordon <smjg_1998 yahoo.com>  
wrote:

 No, because writing <BR/> would make it invalid HTML.


Any chances to get xhtml output? Switch or something?

-- 
Dawid Ciężarkiewicz
Sep 20 2005
prev sibling parent Derek Parnell <derek psych.ward> writes:
On Tue, 20 Sep 2005 16:39:57 +0100, Stewart Gordon wrote:


 Derek Parnell wrote:
 <snip>

 I am hampered by my limited ability to fully understand the DTD specified.
 It has, as does the strict DTD, 
 
   <!ELEMENT BR - O EMPTY                 -- forced line break -->
 
 which means that the BR tag must be an empty element and thus should take
 the form <BR/> rather than <BR>...</BR> . 


 
 <br> or <BR>.  Or if you like, <Br> or <bR>.  Not <BR/>.  In HTML, as 
 opposed to XHTML, there's no such thing as /> at the end of a tag.


Many thanks.

So in short, <br/> is XHTML and <br> is HTML, and DDoc outputs HTML.

-- 
Derek Parnell
Melbourne, Australia
21/09/2005 7:46:33 AM
Sep 20 2005
prev sibling parent reply "Walter Bright" <newshound digitalmars.com> writes:
"Derek Parnell" <derek psych.ward> wrote in message
news:ifpy2f2gg405$.dl2kq2qexzmf.dlg 40tude.net...

 I've tried to convert some of my existing embedded documentation to the


new

 DDoc format. I've found out so far that DDoc is not rich enough to do a
 good job. It is missing some things to make life easier.

 ** It has no support for lists. I find that lists are a common
 documentation construct.


True, but for now you can use HTML list constructs. They'll work. I've also
been thinking of a simple table markup syntax.



 ** It has no support for highlighting user-defined words, and I'm not
 talking about program identifiers etc... I'm talking about arbitrary words
 and phrases that the author wants highlighted.


True, but here as well you can use HTML constructs to do it.



 ** It has no support for multiple output files. Currently, one HTML file


is

 generated for one source file.


I'd phrase that as a one-to-one correspondence between modules and HTML
pages. I don't have a feel for how multiple HTML page output would look or
be used.



 ** It has no support for automatic index generation. Various types of
 source identifiers (eg. functions and global variables) plus author


defined

 bookmarks would be useful to be indexed.
 ** It has no support for an automatically generated Table of Contents.


True, but I was relying on google to do the indexing <g>. A table of
contents is another matter, and eventually Ddoc should do some sort of
automatic T.O.C. generation.


 ** The generated HTML should use <hr/> and <br/> instead of <hr> and <br>
 respectively.


I don't think <hr/> is HTML 4.


 ** The generated HTML uses <dl> without any <dt> and <dd> entries. Why is
 <dl> being used?


Around which? I'll have to go back and look at it.


 ** Instead of using unadorned <p> </p> blocks for sections, you could
 generated style references so people could utilize style sheets. Eg.

    <p><span class=ddoc_section>date:</span> Sep 20, 2005 </p>

 and the style sheet could then define ...

    span.ddoc_section { font-weight: bold }


Yes, Ddoc output should be manipulatable by user supplied style sheets, it's
just that I'm a bit ignorant on how to do all that. It's actually one of my
motivations for doing Ddoc - I bet I'm not the only programmer who is
hampered in creating good looking documentation by not being very fluent in
modern HTML. Having Ddoc do the HTML output automatically, and copying an
existing style sheet that looks good to you, makes it a piece of cake. I
tried to design Ddoc so at least for routine stuff no HTML knowledge is
required.
Sep 20 2005
parent reply "Unknown W. Brackets" <unknown simplemachines.org> writes:
Simplicity and ease of use is a very good goal, if I may say so.

However, different programmers may have different experiences.  A 
younger programmer may have a basic understanding of XML or of XHTML, 
and no understanding of HTML.  While basic HTML may seem simple to you, 
it's because you've seen it.  To someone who has only seen XHTML, it may 
seem more foreign - or it may seem less.  It's just impossible to tell.

Usually, a good compromise can be made.  The output can use basic 
semantic tags that are available in HTML and XHTML.  It can have a few 
classes here and there, which require no stylesheet (in other words, 
which are not used by default, but could be if the user is experienced 
enough to know how.)

As an example, it could output: (although this might be over the top.)

<span class="ddoc_type">real</span>

This would have no visible effect whatsoever.  However, if you knew CSS, 
you might add:

.ddoc_type
{
    color: red;
}

And, then, all types - int, real, dchar, etc. - would be red.

More desirably, a command line option would be available, like -Dc (for 
CSS or classes?) or similar.  Or perhaps not... but that would negate 
the only downside (larger generated page, with class information.)

If I have some time available, would you be willing to look at patches 
to change its output, or perhaps add some sort of argument to specify 
HTML or XHTML output?  If so, which would you be interested in? (and 
which would I be mostly wasting my time to work on?)

-[Unknown]



 Yes, Ddoc output should be manipulatable by user supplied style sheets, it's
 just that I'm a bit ignorant on how to do all that. It's actually one of my
 motivatuions for doing Ddoc - I bet I'm not the only programmer who is
 hampered in creating good looking documentation by not being very fluent in
 modern HTML. Having Ddoc do the HTML output automatically, and copying an
 existing style sheet that looks good to you, makes it a piece of cake. I
 tried to design Ddoc so at least for routine stff no HTML knowledge is
 required.
Sep 22 2005
parent "Walter Bright" <newshound digitalmars.com> writes:
"Unknown W. Brackets" <unknown simplemachines.org> wrote in message
news:dgto0g$2q40$1 digitaldaemon.com...

 Simplicity and ease of use is a very good goal, if I may say so.


Yes.


 However, different programmers may have different experiences.  A
 younger programmer may have a basic understanding of XML or of XHTML,
 and no understanding of HTML.  While basic HTML may seem simple to you,
 it's because you've seen it.  To someone who has only seen XHTML, it may
 seem more foreign - or it may seem less.  It's just impossible to tell.


I agree completely.


 If I have some time available, would you be willing to look at patches
 to change its output, or perhaps add some sort of argument to specify
 HTML or XHTML output?  If so, which would you be interested in? (and
 which would I be mostly wasting my time to work on?)


I think I've found a way that either HTML or XHTML could be generated by
using a simple configuration file. Or even XML. Once I put it out, I would
very much like to see if a configuration file for various formats can be
created.
Sep 24 2005