making macros

One way for you to get a grip on DocBook would be to try out
Eric Raymond's doclifter:

  http://www.catb.o
rg/~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:

  htt
p://www.xml.com/pub/a/2004/03/03/sgmlwiki.html

A few tools for up-translating structured text to DocBook
markup:

  http://docutils.sour
ceforge.net/
  http://docutils.sourceforge.net/sandbox/oliverr/docbook/

  The DocBook writer is not terribly complete yet.

  http://www.xml
mind.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://ww
w.dpawson.co.uk/docbook/index.html


kind regards
Peter Ring

> -----Original Message-----
> From: Chuck Robey [mailto:chuckrchuckr.org]
> Sent: 23. april 2006 23:18
> To: Per Bothner
> Cc: Steven Cogorno; docbooklists.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-unsubscribelists.oasis-open.org
> For additional commands, e-mail: docbook-helplists.oasis-open.org
> 
> 

------------------------------------------------------------
---------
To unsubscribe, e-mail: docbook-unsubscribelists.oasis-open.org
For additional commands, e-mail: docbook-helplists.oasis-open.org