One way for you to get a grip on DocBook would be to try out Eric Raymond's doclifter:
http://www.catb.org/~esr/doclifter/
"The doclifter program translates documents written in troff macros to DocBook."
If you insist on writing a markup shorthand rather than the somewhat verbose XML markup, there's a number of options. If you are really familiar with SGML, you can actually use a normalizing SGML parser to 'fix up' a shorthand. Here's an example:
http://www.xml.com/pub/a/2004/03/03/sgmlwiki.html
A few tools for up-translating structured text to DocBook markup:
http://docutils.sourceforge.net/
http://docutils.sourceforge.net/sandbox/oliverr/docbook/
The DocBook writer is not terribly complete yet.
http://www.xmlmind.com/aptconvert.html
See a list of more up-conversion tools:
http://wiki.docbook.org/topic/DocBookTools#top_Include_ConvertOtherFormatsToDocBook
I have mixed feelings wrt. shorthands vs. valid XML markup. Mostly, I'll write the body of the text with little or no markup, and then add markup later. A structured text format can be helpful (and really nice for documentation embedded in source code). But you won't really get the benefits of XML without using it.
There is a long list of tutorials on the DocBook wiki:
http://wiki.docbook.org/topic/DocBookTutorials
Many of these tutorials appear to be a bit dated wrt. tools and "best practices". Given that you don't have any legacy DocBook documents:
- you should not start any new SGML-based projects
- you should investigate using xinclude rather than entity references
- you should prepare to use namespaces
- you should investigate using Relax NG and Schematron-based validation
In addition to this list and the DocBook wiki, you'd like to sample David Pawson's DocBook FAQ:
http://www.dpawson.co.uk/docbook/index.html
kind regards
Peter Ring
> -----Original Message-----
> From: Chuck Robey [mailto:]
> Sent: 23. april 2006 23:18
> To: Per Bothner
> Cc: Steven Cogorno;
> Subject: Re: [docbook] making macros
>
>
> Per Bothner wrote:
>
> > Steven Cogorno wrote:
> >
> >> You can't do that. There's no facility for creating "macros" that
> >> group elements together. You need to include the entire element
> >> structure.
> >
> >
> > One thing one can do is can design a new format that you
> translate into
> > docbook. But then the input format isn't docbook.
> However, if you want
> > "macros" you can define your own tags, and then write a little xslt
> > script to translate that to standard docbook.
>
> I'm so new to docbook and xml, I am very uneasy to contradict
> people.
> I've read that one of Sun's major contributionns is in the field of
> documentationm which makes me doubly unwilling to contradict. I'm a
> programmer, not a document specialist, or editor. That in
> mind, here I
> go making a fool of myself ...
>
> Yes, it seems you're absolutely right that docbook provides no such
> facilities, but as a programmer, i really never expected any, and
> instead I began looking over tools to see which might serve
> to produce
> such a facility OK, the most difficult would be C, and I
> would only use
> that because of it's very good portability. Another
> possibility would
> be python and the ElementTree, which seems very capable of performing
> this. However, it seems that the xslt processors couild do this very
> nicely, and many xml environments include a xsl processor right along
> with the rest of their tools, so portability is great.
>
> So, something like zsltproc would serve, if I wrote a good
> enough xslt
> script, wouldnt it? Yes, I would want to use an entirely new set of
> elements, which would have to be translated back into docbook
> elements,
> but that's exactly what I suggested, exactly how the mm
> macros work with
> groff.
>
> So (note I tend to take a bit to repond usually, fellas),
> tell me again
> how I'm wrong, please. I'm stubborn, I know that, but I can see the
> light, given enough time. Oh, if you consider that I am right, then
> what I'm after is NOT the script to do this, I would write
> that. It's
> in the definition of what serve as macros. I mean, if I
> chose something
> like mm's chapter entries, or the llist facility, as a macro
> target, and
> I called this macro 'chuck1' (I couldnt name things at all, guys, I'm
> quite poor at that), say i asked for lists, could I get some help in
> formulating (in maybe meta-language) what might the macro be?
>
> I'll write the processor, but I'm not a very good docbook author yet.
>
> >
> > This translation could be combined with regular dcobook processing,
> > by adding extra rules to the standard docbook xslt scripts
> for handling
> > the new tags.
> >
> > An alternative: The GNU texinfo format is a lot less verbose than
> > docbook, and you can translate texinfo into docbook. (Last year
> > I made numerous fixes to the makeinfo program for its option to
> > generate docbook instead of the default info format.) However,
> > texinfo is a completely different format from docbook - it's not
> > even XML.
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail:
> For additional commands, e-mail:
>
>
