Re: [docbook] making macros

[Chuck Robey <chuckr@chuckr.org>]

Peter Ring wrote:

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.
      

Wow,, I am really impressed, this email is very easily the single mmost on-topic email I have received, and I need to read all of the references, thanks.

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