[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Re: [docbook] making macros
Peter Ring wrote:
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.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 youtranslate intodocbook. 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 scriptsfor handlingthe 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 |
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]