Re: [docbook-apps] Show off what you've done with Docbook
On 09/11/2015 12:56 PM, Katie Welles wrote: +-- | Have any of you PDF + HTML output with Docbook? If anyone has | such a project and will be willing to show it off, send some URLs! +-- I've been using DocBook as a vehicle for literate programming for well over ten years now. Here are several dozen examples including one suite that contains roughly 50k lines of Python: http://www.nmt.edu/~shipman/soft/litprog/ Here's my stylesheet customization layer, also a literate program: http://www.nmt.edu/~shipman/doc/doc5style/ There is a reason for having both PDF and HTML output that I rarely see mentioned. When I read documentation for a tool I want to use, I want to be sure that I've read or at least skimmed the complete documentation. Too often in my novice days I would read a little, try to use the tool, and find out later that features discussed in one of the parts I skipped could have made life much easier. A chunked HTML rendering is very convenient, but sometimes when I'm clicking around a heavily cross-linked structure, I have to wonder if I've seen all the content, especially if the HTML does not provide a table of contents. With a PDF, I can read (or skim) the whole thing sequentially and be confident that I didn't miss anything. I am extremely grateful to the people who built DocBook, and most especially to Norman Walsh who build the modular stylesheets, and the indispensable Bob Stayton without whom I could never have built a presentable style. Happy documenting, John Shipman (j...@nmt.edu), Adjunct Professor of Computer Science Cramer 212, New Mexico Tech, Socorro, NM 87801 (505)249-3839 - To unsubscribe, e-mail: docbook-apps-unsubscr...@lists.oasis-open.org For additional commands, e-mail: docbook-apps-h...@lists.oasis-open.org
Re: [docbook-apps] Restrictive Docbook XML editor which enforces Docbook schema?
On Thu, 15 Jan 2015, Dan Shelton wrote: +-- | Is there a Docbook XML editor which enforces the Docbook | schema during editing? | | I am looking for an editor which loads the Docbook XML schema and then | only allows the creation of tags which are allowed at the current | position in the XML document. +-- This emacs mode does all that. I use it all day every day: http://www.nmt.edu/~shipman/doc/nxml/ Best regards, John Shipman, Web Developer, National Radio Astronomy Observatories; j...@nmt.edu, http://www.nmt.edu/~shipman/ - To unsubscribe, e-mail: docbook-apps-unsubscr...@lists.oasis-open.org For additional commands, e-mail: docbook-apps-h...@lists.oasis-open.org
[docbook-apps] Literate customization layer
Here at the New Mexico Tech Computer Center, we've been using DocBook for all our official publications for over ten years now. I thought some of you might like to see our customization layer. It is literate in the Don Knuth sense---the actual XSLT is embedded in the documentation explaining what each piece does. http://www.nmt.edu/tcc/doc/docbook43/ims/ Customization of the 4.3 DocBook-XSL Stylesheets for the TCC This version is for 4.3; our 5.x version is in development. Any comments or suggestions would be most welcome. Best regards, John Shipman (j...@nmt.edu), Applications Specialist New Mexico Tech Computer Center, Speare 146, Socorro, NM 87801 (575) 835-5735, http://www.nmt.edu/~john ``Let's go outside and commiserate with nature.'' --Dave Farber - To unsubscribe, e-mail: docbook-apps-unsubscr...@lists.oasis-open.org For additional commands, e-mail: docbook-apps-h...@lists.oasis-open.org
[docbook-apps] XSL-FO generation tool available
I've just put the finishing touches on a Python module to assist in the programmatic construction of XSL-FO files. It's built on top of lxml: http://www.nmt.edu/tcc/projects/fohelpers If you find this useful or have any comments, I'd like to hear about it. I realize XSL-FO is a dead standard, but so long as DocBook and DITA are around, it'll be supported. Can anyone suggest a better route from Python to PDF? Best regards, John Shipman (j...@nmt.edu), Applications Specialist New Mexico Tech Computer Center, Speare 146, Socorro, NM 87801 (575) 835-5735, http://www.nmt.edu/~john ``Let's go outside and commiserate with nature.'' --Dave Farber - To unsubscribe, e-mail: docbook-apps-unsubscr...@lists.oasis-open.org For additional commands, e-mail: docbook-apps-h...@lists.oasis-open.org
[docbook-apps] Python to PDF via XSL-FO
As much as I love XSLT (half-kidding here), I have several applications to generate PDFs from databases, and from other sources that XSLT can't reach directly. Since I discovered SQLAlchemy (http://www.sqlalchemy.org), life is much nicer: In Python, I can pull data from SQL databases without getting any actual SQL on my paws. These applications use Python and its wonderful lxml module to produce XSL-FO files, which I can then run through XEP or FOP. I've built a little Python module to assist in the generation of XSL-FO: http://www.nmt.edu/tcc/projects/fohelpers If anyone finds this module useful, or if you have feedback on its usefulness, I would be delighted to hear from you. Are there other mailing lists that might reach potential users? Best regards, John Shipman (j...@nmt.edu), Applications Specialist, NM Tech Computer Center, Speare 146, Socorro, NM 87801, (575) 835-5735, http://www.nmt.edu/~john ``Let's go outside and commiserate with nature.'' --Dave Farber - To unsubscribe, e-mail: docbook-apps-unsubscr...@lists.oasis-open.org For additional commands, e-mail: docbook-apps-h...@lists.oasis-open.org
Re: [docbook-apps] Indexing.
I've indexed three 500-page books, but never in DocBook. However, I'd like to reinforce Thomas Schraitle's point that it is both important and nontrivial. The first thing I'd recommend is to read up on indexing. The Wikipedia page is a good starting point. http://en.wikipedia.org/wiki/Index_%28publishing%29 In earlier eras I used the Chicago Manual of Style to learn about good practices. There are certain very specific fetishes I have about indexing that I see violated quite often. The index to the Guide to LaTeX by Helmut Kopka has an example of a horrible flaw that severely compromises its usefulness: if a major topic is continued over a page break, the major topic is NOT repeated on the continuation column. Think about how you use an index: you depend on the top words of each column to be in alphabetical order. But on page 584 of Kopka's book, the entire column is a continuation of major topic package, but the first entry is amsmath. So you think you're in the a section of the index, but you're actually in the p section! It should look like this, but in many books I don't see a line like the first one: package (continued) amsmath, 191, 269-270 amsopn, ... An obvious application for marks. My next suggestion may slightly increase the page count, so I never mentioned it back in the day when dead trees were the only route to publication. However, the increase is small, and inexcusable if you expect most people will e-read your book. As an example, the discussion of the amsmath package should have two entries: amsmath package, 372 packages, 366 amsmath, 372 In general, if an indexable phrase has more than one important word, it should appear in the index under each of those words. I can't give you any useful suggestions on current tools. Back in the day I just invented a file format for entering all the indexable references and then wrote my own software in C to generate the index in TeX. This approach assumes that the page numbers are all cast in stone, which was fine because in my cases the rest of the book had all been put to bed. Best regards, John Shipman (j...@nmt.edu), Applications Specialist, NM Tech Computer Center, Speare 146, Socorro, NM 87801, (575) 835-5735, http://www.nmt.edu/~john ``Let's go outside and commiserate with nature.'' --Dave Farber - To unsubscribe, e-mail: docbook-apps-unsubscr...@lists.oasis-open.org For additional commands, e-mail: docbook-apps-h...@lists.oasis-open.org
Re: [docbook-apps] How to remove extra newline in programlisting
On Wed, 13 Oct 2010, Jason Gilmore wrote: +-- | I am however running into a strange issue involving programlisting | elements in which the enclosed text is delimited by ![CDATA[...]]. | When I convert from Docbook to PDF using oXygen (using the Saxon 6.5 | transformer), my program listing's include two extra newlines at the | top and one at the bottom when the programlisting's look like this: +-- Here's how I format code snippets (with a little context to show the indentation): para This code destroys Western Snivelization: /para programlisting role='outFile:hardloop.bas' 10 PRINT BASIC IS OLDER THAN DIRT 20 GOTO 10 30 END /programlisting para And now... /para We're especially sensitive to how programlisting works because we use this element for literate programming: the code snippets are the ones that get executed. Remarks on the above example: a. Whitespace, including newlines, is always allowed before the closing '' of a tag. b. We use the 'role' attribute, which is reserved for application use, to mark the source file to which each fragment is written. The lines written to file hardloop.bas look like this: 10 PRINT BASIC IS OLDER THAN DIRT 20 GOTO 10 30 END c. Note that the first code line is misaligned relative to the following line because of the ''. This is annoying only while you're editing the source; it looks correct in HTML and PDF output. With CDATA it'd look like this: programlisting ![CDATA[ 10 PRINT BASIC IS OLDER THAN DIRT 20 GOTO 10 30 END ]]/programlisting Here's a boatload of literate programming examples and some pointers to the why and how in our local practice: http://www.nmt.edu/~shipman/soft/litprog/ Happy happy joy joy, John Shipman (j...@nmt.edu), Applications Specialist, NM Tech Computer Center, Speare 119, Socorro, NM 87801, (575) 835-5735, http://www.nmt.edu/~john ``Let's go outside and commiserate with nature.'' --Dave Farber - To unsubscribe, e-mail: docbook-apps-unsubscr...@lists.oasis-open.org For additional commands, e-mail: docbook-apps-h...@lists.oasis-open.org
Re: [docbook-apps] Docbook for industrial usage
+-- | Hi, yesterday I talked with Camille on IRC about getting | docbook used more in industry. I am searching for companies | that already use it and that could give a good example about | what they do with docbook and why they use it. And I also got | one first contact I am going to write to. +-- Not exactly industry, but all our college's computer center publications are done in DocBook 4.3 (yes, yes, I know, I'll move to 5.0 if I ever finish migrating all our old HTML to our new Pylons site). http://www.nmt.edu/tcc/help/pubs/index/ I currently maintain several hundred DocBook documents. DocBook is also my preferred framework for literate programming: http://www.nmt.edu/~shipman/soft/litprog/ When I start a new coding project, the first thing I do is set up the directory for DocBook and write up the requirements. Next, I flesh out the specification. Next step is to write up the design and include diagrams and tables for such design artifacts as entity-relationship diagrams and schema pictures. Then the code goes right in the same document so it is single-sourced there. Here's our peer-reviewed journal article on this subject: Stavely, Allan, Lynda Walsh, and John Shipman. Lightweight literate programming: a documentation practice. Technical Communication 55(1), Feb. 2008. I love DocBook and wish to thank all the many people who built it and continue to maintain and enhance it. A marvelous tool and the pivot around which all my documentation and software design practice rotate. Best regards, John Shipman (j...@nmt.edu), Applications Specialist, NM Tech Computer Center, Speare 119, Socorro, NM 87801, (575) 835-5735, http://www.nmt.edu/~john ``Let's go outside and commiserate with nature.'' --Dave Farber - To unsubscribe, e-mail: docbook-apps-unsubscr...@lists.oasis-open.org For additional commands, e-mail: docbook-apps-h...@lists.oasis-open.org
Re: [docbook-apps] Compact DocBook ?
+-- | I'm hoping to embed DocBook within some Java code (as | comments). Along with some support utilities, this should | allow embedding of documentation next to the code it describes. | This is somewhat similar to JavaDoc, but: | | a. using DocBook vocabulary, | | b. to be included within end-user documentation. | | The thought of writing DocBook XML inside Java comments isn't appealing. +-- Why not turn the whole process inside out? http://www.nmt.edu/~shipman/soft/litprog/ For several years now, all my serious coding is done in lightweight literate programming (LLP) style. The idea is to have the documentation contain the program, not vice versa. Here's how I develop code nowadays. 1. Write up the external interface in DocBook. 2. Document the big picture parts of the design, also in DocBook. For a small project, this can be the same document as the external spec; for substantial projects, I'll start a separate Internal Maintenance Specification. 3. Write the program as a continuous narrative with embedded code blocks contained within DocBook programlisting elements. To distinguish example code blocks from live code blocks, I used the extension 'role' attribute to route the code into the files from which it will be run or compiled. Here's an example: para The first lines make this script self-executing, and point back to this documentation: /para programlisting role='outFile:myscript.py' #!/usr/bin/env python # myscript.py: This script... # For documentation, see http://... - HTML output from DocBook import sys ... /programlisting Writing a script to extract the source code files took me about an hour, including all documentation. It's trivial in any language with a decent XML toolset; I used Python and lxml. Note that you can include any number of files in any number of languages. One drawback of JavaDocs is that it works only with Java. Sometimes the project includes non-Java files, such as CSS stylesheets; why not include them in literate form as well? See the URL above for the code extractor and several dozen complete projects done in this style. The originator of Lightweight Literate Programming is my colleague Dr. Allan Stavely, based on the classic 1980s-era literate programming idea from Dr. Don Knuth. Best regards, John Shipman (j...@nmt.edu), Applications Specialist, NM Tech Computer Center, Speare 119, Socorro, NM 87801, (575) 835-5735, http://www.nmt.edu/~john ``Let's go outside and commiserate with nature.'' --Dave Farber - To unsubscribe, e-mail: docbook-apps-unsubscr...@lists.oasis-open.org For additional commands, e-mail: docbook-apps-h...@lists.oasis-open.org
Re: [docbook-apps] DocBook Customization -- Subsets
+-- | We've looked at the simplified version of DocBook and it's TOO simple. | We have a couple of examples of local style manuals (thank you!). If | anyone else wants to share their tag subsets, that would be gratefully | received. We appreciate the goal of reducing complexity and | ambiguity--makes sense--but we're less clear where to begin for a set | of books above the article level. +-- Our local style doesn't support the 'book' element---all our publications are articles---but it's enough for our few dozen separate publications. Here's our user manual: http://www.nmt.edu/tcc/help/pubs/docbook/ This document has two purposes: - It has localizing information, like where in our file system you can get model Makefiles, and how to use xep (which we love and have under an academic license). - Since I also do the stylesheet customization, the approach was to describe only the tags that are decently supported in our stylesheet layer. Here's our local stylesheet layer, in literate form (the definitive versions of the XSLT files displayed here actually reside in the DocBook source): http://www.nmt.edu/tcc/doc/docbook43/ims/ Bon appetit, John Shipman (j...@nmt.edu), Applications Specialist, NM Tech Computer Center, Speare 119, Socorro, NM 87801, (505) 835-5950, http://www.nmt.edu/~john ``Let's go outside and commiserate with nature.'' --Dave Farber - To unsubscribe, e-mail: docbook-apps-unsubscr...@lists.oasis-open.org For additional commands, e-mail: docbook-apps-h...@lists.oasis-open.org
Re: [docbook-apps] documenting code
+-- Dave Pawson: | Yet again, quote | | A small Python script extracts one or more source files from | the document, and these are the executable form of the program. | /quote | | That seems wrong John? +-- What exactly is wrong with that? I have a Makefile set up so I type: make code and it runs my Python script, which extracts the source files. When I say they are the executable form of the program, they are exactly that for Python, Relax NG, and XSLT. For a compiled language there would clearly be a compile step. Sorry I didn't mention that, but I haven't used any compiled languages for over ten years. +-- | Another problem I have, a long command line, e.g. calling | java, saxon for a transform, | docbook has no | | linejava -cp . | linebreak/main.class | linebreak/param1 | etc | | To enable XSLT to re-build a single line from one | split, for the sake of convenience? +-- This is another problem I haven't encountered. I usually keep my lines short (75 characters for the current toolchain). I don't have any useful ideas at the moment. In my toolchain, you can have lines of any length. I have automatic line wrapping set up for the documentation side of the toolchain. Another reply on this thread said that they prefer to keep the documentation inside the code, rather than the literate approach wherein the code is inside the documentation. The drawback to their approach is that you need a different extractor for each language. With the literate approach, it is not necessary to be sensitive to any particular language's syntax. Also, one can have a literate document with fragments in multiple different languages. I have some examples that contain both a Relax NG schema and Python code that operates on XML files that conform to that schema. Best regards, John Shipman (j...@nmt.edu), Applications Specialist, NM Tech Computer Center, Speare 119, Socorro, NM 87801, (505) 835-5950, http://www.nmt.edu/~john ``Let's go outside and commiserate with nature.'' --Dave Farber - To unsubscribe, e-mail: docbook-apps-unsubscr...@lists.oasis-open.org For additional commands, e-mail: docbook-apps-h...@lists.oasis-open.org
Re: [docbook-apps] documenting code
On Mon, 5 Jan 2009, Dave Pawson wrote: +-- | I've seen Norm using docbook to tangle and weave XML. | I'm wondering how well docbook would work for code? +-- Been doing it for years. Have a look at: http://www.nmt.edu/~shipman/soft/litprog/ This pages has links to lots of Python examples, but also literate expositions of several Relax NG schemas, an emacs Lisp application, and the XSLT customization layer for our local DocBook toolchain. Best regards, John Shipman (j...@nmt.edu), Applications Specialist, NM Tech Computer Center, Speare 119, Socorro, NM 87801, (505) 835-5950, http://www.nmt.edu/~john ``Let's go outside and commiserate with nature.'' --Dave Farber - To unsubscribe, e-mail: docbook-apps-unsubscr...@lists.oasis-open.org For additional commands, e-mail: docbook-apps-h...@lists.oasis-open.org
Re: [docbook-apps] suppressing table captions
Is there some reason you can't use informaltable? It has the same content model as table, except no caption element. Best regards, John Shipman ([EMAIL PROTECTED]), Applications Specialist, NM Tech Computer Center, Speare 119, Socorro, NM 87801, (505) 835-5950, http://www.nmt.edu/~john ``Let's go outside and commiserate with nature.'' --Dave Farber On Fri, 22 Feb 2008, Mayo Jordanov wrote: +-- | I'm trying to suppress table and figure captions. I've tried playing with | formal.title.properties and object.title.markup but so far I've been quote | unsuccessful. The table markup (below) is rather simple, and I'm processing | it with the FO stylesheets. I'm trying to get rid of the caption completely, | so both the Table 1 as well as the caption tag will be ignored | (regardless of it being defined or not). | | Any suggestions? | | thank you, | Mayo jordanov | | |table | !-- captionSample HTML Table/caption -- | thead |tr | thCol 1/th | thCol 2/th |/tr | /thead | tbody |tr | thRow 1/th | tdR1 C2 value/td |/tr | /tbody |/table +-- - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: [docbook-apps] Tools for generating Docbook programlisting fragments?
On Sat, 25 Aug 2007, Tommy Nordgren wrote: +-- | Do anyone know of a library for generating DocBook | programlisting fragments from source code listings marked up | with special comments. The purpose is to generate the Docbook | source and program language source, from a common | specification. +-- If single-sourcing is your goal, why not make the DocBook document your single source? Then you need only strip out the executable parts with a simple filter. My colleague Dr. Allan Stavely calls this 'lightweight literate programming'. See my page for the tools and a few dozen examples ranging up to 4000+-line sources: http://www.nmt.edu/~shipman/soft/litprog/ I don't know if this fits your application, but I thought this would be a good opportunity for me to promote one of my pet techniques. :) +-- | I've tested filtering a xml file containing a programlisting | DocBook element through a custom stylesheet, but so far I've | been unable to avoid getting extra whitespace, when doing it | this way. +-- I code mainly in Python, which is rather sensitive to whitespace. Here's how I format code fragments: para This next section...blah blah blah /para programlisting role='outFile:myscript.py' Line 1 Line 2 Line 3 /programlisting role='outFile:myscript.py' para Etc. /para Line breaks are perfectly legal within XML tags just before the closing '' or '/'. So the above formatting produces three lines, with newline terminators, and nothing else. This puts the work on you instead of the filter, but it works for me. Best regards, John Shipman ([EMAIL PROTECTED]), Applications Specialist, NM Tech Computer Center, Speare 119, Socorro, NM 87801, (505) 835-5950, http://www.nmt.edu/~john ``Let's go outside and commiserate with nature.'' --Dave Farber - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: [docbook-apps] Tools for generating Docbook programlisting fragments?
Oops, I made a cut and paste error! The fragment should be: +-- | para | This next section...blah blah blah | /para | programlisting role='outFile:myscript.py' | Line 1 | Line 2 | Line 3 | /programlisting | para | Etc. | /para +-- John Shipman ([EMAIL PROTECTED]), Applications Specialist, NM Tech Computer Center, Speare 119, Socorro, NM 87801, (505) 835-5950, http://www.nmt.edu/~john ``Let's go outside and commiserate with nature.'' --Dave Farber - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
[docbook-apps] TeX math in DocBook
On Thu, 10 May 2007, Stefano Sabatini wrote: +-- | Stefano Sabatini [EMAIL PROTECTED] wrote on Wed, 9 May | 2007 11:38:19 +0200: | | I would like to avoid to use MathML, due to its need for a graphical | editor, so using the compact tex notation +-- I've been trying for some time to find a way to get TeX to output scalable PDFs that work within DocBook. I finally worked out a rather kludgey route that works. Equations in TeX or LaTeX can be included either as block elements or as inlines. It doesn't use MathML or SVG, and it works fine with XEP. Equations are scalable in the PDF output, but rasterized in the HTML output. This particular toolchain may be documented somewhere, but I couldn't find it easily in one place. The procedure is described here: http://www.nmt.edu/tcc/help/pubs/docbook43/tex-math.html This is a section of the documentation for our local DocBook toolchain. That documentation starts here: http://www.nmt.edu/tcc/help/pubs/docbook43/ This documentation is intended only for our local users; your site may or may not have the necessary installs. If you would like to see how we've customized the style sheets, we have our customization layer up in literate-programming form here: http://www.nmt.edu/tcc/doc/docbook43/ims/ Best regards, John Shipman ([EMAIL PROTECTED]), Applications Specialist, NM Tech Computer Center, Speare 119, Socorro, NM 87801, (505) 835-5950, http://www.nmt.edu/~john ``Let's go outside and commiserate with nature.'' --Dave Farber - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
