Re: Xcode 3.0 DocSet example
Re: Xcode 3.0 DocSet example
- Subject: Re: Xcode 3.0 DocSet example
- From: Ronald Hayden <email@hidden>
- Date: Sun, 18 Nov 2007 15:59:59 -0800
Nice work -- it's great to see some interesting use of doc sets
starting to develop.
The DocSet .xml format has a few oddities to it, though. For reasons
that are entirely unclear to me, a 'Node' can have both a Path and a
File. The node must have a Path, but the File part is optional
because the Path can also be the 'full path' to a file (ie,
<path>/etc/passwd</path>, or <path>/etc/</path> <file>passwd</file>,
but not <file>/etc/passwd</file>). Its definitely confusing and near
as I can tell completely superfluous, I ended up eventually just using
paths exclusively. It would also be nice to have table of content
entries that don't have a .html or other content associated with them.
I end up having several 'duplicate' entries just to define my ToC
hierarchy.
Actually, both File and Path are optional, and you can definitely have
a TOC node with no associated content. The reason we allow for both
is so you can use the Path to point to a localized bundle, after which
the File can point to a particular location within the .lproj directory.
If there's some particular case where a node with no associated path
or file doesn't seem to be working, feel free to send me the info and
we'll look into it.
-- Ron
On Nov 13, 2007, at 3:37 PM, John Engelhart wrote:
For those of you interested in the new Xcode 3.0 DocSet
functionality..
I've been working on an open source project lately, it's an
Objective-C framework for regular expressions using the PCRE library
available at http://regexkit.sourceforge.net/
Since it's a framework, it obviously requires quite a bit of
documentation to be useful. I became really frustrated with the
provided headerdoc tools so I ended up rolling my own documentation
system for the project. I stuck with the headerdoc format since quite
a bit of the documentation was already in that format. I ended up
with a couple of perl scripts to extract the headerdoc information,
parse out various declarations and what not, and put everything in to
a SQLite database. Once in the database, the backend HTML generation
is a snap, obviously, including automatic table of contents
generation. The HTML is heavily marked up so you an style it easily
with CSS. The CSS I use looks identical to the format used by Apple,
and another benefit of having it highly structured with an eye towards
CSS is that a print media style sheet is also provided which formats
things pretty closely to the Apple .pdf's with the same .html.
The HTML documentation can be viewed at
http://regexkit.sourceforge.net/Documentation/
Another benefit of having everything in a database is that once I saw
the DocSet documentation, it took very little time to write a back end
that just output the database contents in the .xml format docsetutil
was looking for. The first release with DocSet documentation was on
Oct 29th, Leopard being released on Oct 26th. The .html content was
reused without much modification. One problem I had was apple uses
"//apple_ref/" anchors in their mark up. I moved away from this
because as part of the creation process, all the HTML gets spell
checked and run through `tidy`. Unfortunately, anchor names in HTML
have an oddly restrictive legal character set, and the "//apple_ref/"
format is not legal html. This results in hundreds and hundreds of
warnings from tidy about invalid HTML, which effectively kills the
usefulness of checking with tidy. Luckily, perl and a database make a
great combo, and a simple search and replace regex of the valid html
is re-written in to Apples preferred //apple_ref/ format for the
DocSet documentation.
The whole thing is pretty quick. A clean build takes about 30 seconds
on my lowly Powerbook G4 1.5Ghz for everything, to parse all the
headers (244KB), parse all the #defines from gcc (gcc -E -Wp,-dM
-std=gnu99 -x objective-c ...), resolve and rewrite all @link's,
generate the HTML + table of contents (822KB), re-write all the HTML
in apple_ref format, generate the Nodes.xml and Tokens.xml (270KB)
files for docsetutil, and have docsetutil generate it's private
indexes and bundle the whole thing up in a .xar for automatic
subscription updates. `headerdoc2html` can take 30 seconds on a
single header file at times.
The DocSet .xml format has a few oddities to it, though. For reasons
that are entirely unclear to me, a 'Node' can have both a Path and a
File. The node must have a Path, but the File part is optional
because the Path can also be the 'full path' to a file (ie,
<path>/etc/passwd</path>, or <path>/etc/</path> <file>passwd</file>,
but not <file>/etc/passwd</file>). Its definitely confusing and near
as I can tell completely superfluous, I ended up eventually just using
paths exclusively. It would also be nice to have table of content
entries that don't have a .html or other content associated with them.
I end up having several 'duplicate' entries just to define my ToC
hierarchy.
Hopefully seeing a working example will be helpful to someone out
there. The documentation system itself isn't terribly generalized at
the moment, it's unlikely you could pull it out and drop it in to
something else without a lot of effort. It's been one of those things
that's sort of grown organically to solve a specific need I had.
_______________________________________________
Do not post admin requests to the list. They will be ignored.
Xcode-users mailing list (email@hidden)
Help/Unsubscribe/Update your Subscription:
This email sent to email@hidden
_______________________________________________
Do not post admin requests to the list. They will be ignored.
Xcode-users mailing list (email@hidden)
Help/Unsubscribe/Update your Subscription:
This email sent to email@hidden