| Thread overview | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
September 20, 2005 DDoc richness | ||||
|---|---|---|---|---|
| ||||
 | 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 | |||
Permalink
ReplySeptember 20, 2005 Re: DDoc richness | ||||
|---|---|---|---|---|
| ||||
 Posted in reply to Derek Parnell | 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. | |||
September 20, 2005 Re: DDoc richness | ||||
|---|---|---|---|---|
| ||||
 Posted in reply to Stewart Gordon | 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?
| |||
September 20, 2005 Re: DDoc richness | ||||
|---|---|---|---|---|
| ||||
Posted in reply to Stewart Gordon | 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 | |||
September 20, 2005 Re: DDoc richness | ||||
|---|---|---|---|---|
| ||||
 Posted in reply to Derek Parnell | "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. | |||
September 20, 2005 Re: DDoc richness | ||||
|---|---|---|---|---|
| ||||
Posted in reply to Derek Parnell | 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. | |||
September 20, 2005 Re: DDoc richness | ||||
|---|---|---|---|---|
| ||||
 Posted in reply to Stewart Gordon | 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 | |||
September 20, 2005 Re: DDoc richness | ||||
|---|---|---|---|---|
| ||||
Posted in reply to Stewart Gordon | 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 | |||
September 22, 2005 Re: DDoc richness | ||||
|---|---|---|---|---|
| ||||
 Posted in reply to Walter Bright | 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.
| |||
September 24, 2005 Re: DDoc richness | ||||
|---|---|---|---|---|
| ||||
Posted in reply to Unknown W. Brackets | "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. | |||
Copyright © 1999-2021 by the D Language Foundation