RE: [docbook] making macros

["Peter Ring" <PRI@magnus.dk>]

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:chuckr@chuckr.org]
> Sent: 23. april 2006 23:18
> To: Per Bothner
> Cc: Steven Cogorno; docbook@lists.oasis-open.org
> 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: docbook-unsubscribe@lists.oasis-open.org
> For additional commands, e-mail: docbook-help@lists.oasis-open.org
> 
>