Mailing Lists: Apple Mailing Lists
Image of Mac OS face in stamp
Re: HEADERDOC: <code> or <pre>, HTML vs XML
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: HEADERDOC: <code> or <pre>, HTML vs XML



Greg Hurrell wrote, on 2004-02-14:

Two related points/questions:

1. In this <http://opendarwin.org/bugzilla/show_bug.cgi?id=1032> bug report there's a patch for getting HeaderDoc to respect whitespace inside <pre></pre> tags, which is great for including sample code inside HeaderDoc comments. (Although as an aside, I think it would probably be better to use <code></code> tages to keep HeaderDoc closer to the JavaDoc style <http://java.sun.com/j2se/javadoc/writingdoccomments/>).

<code> is only useful for keywords and names that should appear in typewriter font.
It does nothing to make HTML respect spaces and linefeeds, which is common in code examples.

So, both <code> and <pre> are useful - and are usually rendered in the same font too.

2. Now, it seems to me that HeaderDoc is fairly strongly tied to the idea of producing HTML output. But still, I see references to XML in the source code and it appears you can output to XML as well if you supply the undocumented "-X" switch on the command line. Not sure what caveats might exist with respect to the use of this feature.

But, given that HeaderDoc seemingly can produce more than one type of output (fantastic!), I am hesitant to use HTML-specific markup (such as <code></code>) inside the HeaderDoc comments.

<code> is valid XML as well. At least in theory (what DTD?).

Get the point though. e.g. Javadoc is very HTML-oriented...

I was wondering if a better alternative might be a pair of new HeaderDoc keywords:

@samplestart
code inbetween these markers is output literally, whitespace is respected etc
@sampleend

I thought you already had enough problems with @ signs ? :-)

I know a little bit of Perl, but not enough to know if this would be a good idea or not, or what potential pitfalls might await. Also, I don't know whether there's new stuff in HeaderDoc 8 which makes this discussion redundant.

It seems to be doing better, at least.

--anders
_______________________________________________
headerdoc-development mailing list | email@hidden
Help/Unsubscribe/Archives: http://www.lists.apple.com/mailman/listinfo/headerdoc-development
Do not post admin requests to the list. They will be ignored.




Visit the Apple Store online or at retail locations.
1-800-MY-APPLE

Contact Apple | Terms of Use | Privacy Policy

Copyright © 2011 Apple Inc. All rights reserved.