"Stewart Gordon" <smjg_1998@yahoo.com> wrote in message news:dfh6i0$119b$1@digitaldaemon.com...
> If the output is not HTML, then the reader of the output will just see
> &, l, t, ; in the rendered document.
> Under your current proposal, if
> someone wants to generate non-HTML documentation from source files
> written for HTML output, he/she/it will have to go through the source
> files replacing all &lt; with <.
> And then when it's time to update the
> HTML documentation again, go through changing it back while having a
> care not to alter those that are part of the code itself.
>
> It should be as possible as possible to write code documentation that works regardless of output format.  Of course converting all HTML tags into the target format isn't going to be easy, but translating &lt; into < if the output format isn't HTML certainly is.

You're right that converting named character entities isn't a big problem, and that if the doc generator generates non-HTML output, it should make some attempt to do so.

Walter wrote:
> "Stewart Gordon" <Stewart_member@pathlink.com> wrote in message
> news:dfekd2$210h$1@digitaldaemon.com...
>> In article <dfa6th$190j$1@digitaldaemon.com>, Walter says...
>>> "Stewart Gordon" <smjg_1998@yahoo.com> wrote in message
>>> news:df9keh$kvi$1@digitaldaemon.com...
>> <snip>
>>>> It ought to be specified that HTML character entities, at least &lt;
>>>> &gt; &amp; will be rendered as their respective characters regardless
> of
>>>> the output format.  That way, it would be possible to use these symbols
>>>> in documentation and they will still work when generating documentation
>>>> in non-HTML.
>>> Since the D source character set is unicode, any unicode characters can
> be
>>> embedded. Using character entities will simply be copied to the output.
>> <snip>
>>
>> I don't see what that's to do with my point.  How does one embed a less
> than
>> sign then?
> 
> I am not understanding what the issue is? If you use < characters, they get
> placed into the output. If that output is html, it may get interpreted as a
> tag. Therefore, you should probably use &lt;, which will get echoed as &, l,
> t, ; to the output.
> 
> 
Perhaps this is a place where (embedded) macros should be allowed, e.g.:

html = True;
static if (html == False)
{    /++ Micros:
         "<" ::= "&lt;"
     +/
}
else
{   // well, no else case is needed
}