Thread: [A-a-p-user] About the docs
Brought to you by:
vimboss
From: Adriaan de G. <ad...@cs...> - 2003-07-30 17:17:53
|
Is there any particular reason the docs are written in SGML docbook, as opposed to XML docbook? As far as I know, all you need to convert XML docbook to something sensible is xsltproc, whereas SGML needs the much heavier jade. (Admittedly, I'm coming from the KDE camp, and have all the tools for the docs for that invisibly installed, so XML docbook seems "free" to me). I'll do the conversion if that helps any; the XML docbook files and stylesheets that I know of (all from KDE) are either GPL or LGPL, so they should be usable for AAP as well. -- pub 1024D/FEA2A3FE 2002-06-18 Adriaan de Groot <gr...@kd...> Key fingerprint = 934E 31AA 80A7 723F 54F9 50ED 76AC EE01 FEA2 A3FE |
From: Bram M. <Br...@mo...> - 2003-07-30 19:44:36
|
Adriaan de Groot wrote: > Is there any particular reason the docs are written in SGML docbook, as > opposed to XML docbook? As far as I know, all you need to convert XML > docbook to something sensible is xsltproc, whereas SGML needs the much > heavier jade. (Admittedly, I'm coming from the KDE camp, and have all > the tools for the docs for that invisibly installed, so XML docbook > seems "free" to me). I'll do the conversion if that helps any; the XML > docbook files and stylesheets that I know of (all from KDE) are either > GPL or LGPL, so they should be usable for AAP as well. I had been recommended to use docbook format (so that the docs could be converted into just about any other format). I just used a few examples and tuned them to make it work (which was less easy than it sounds). I don't know the essential difference between SGML docbook and XML docbook. Can both be converted to nice HTML and PDF? Are both documented properly? I have been using the on-line version of the O'Reilly book: http://www.docbook.org/tdg/en/html/docbook.html . It looks it can be used both for the SGML and XML version, but it's not very clear about this. The book was written in a very technical way, it's quite hard to use. The less tools we need the better. Now that I have used docbook for a while I long back to MS-Word, not a good sign... -- hundred-and-one symptoms of being an internet addict: 15. Your heart races faster and beats irregularly each time you see a new WWW site address in print or on TV, even though you've never had heart problems before. /// Bram Moolenaar -- Bram@Moolenaar.net -- http://www.Moolenaar.net \\\ /// Creator of Vim - Vi IMproved -- http://www.Vim.org \\\ \\\ Project leader for A-A-P -- http://www.A-A-P.org /// \\\ Help AIDS victims, buy here: http://ICCF-Holland.org/click1.html /// |
From: Jean J. <je...@up...> - 2003-07-30 20:48:41
|
Hi Bram > I don't know the essential difference between SGML docbook and XML > docbook. Can both be converted to nice HTML and PDF? They're meant to be equivalent to write with. Docbook XML can be processed with more tools, and the XML stylesheets are under more active development as far as I can tell. I'd recommend using the XML version. > Are both > documented properly? I have been using the on-line version of the > O'Reilly book: http://www.docbook.org/tdg/en/html/docbook.html . It > looks it can be used both for the SGML and XML version, but it's not > very clear about this. I also use that book, and I skipped Docbook SGML entirely. It is rather technical, but no more than the Vim helpfiles :] Here is a book about the XSL stylesheets in particular: DocBook XSL: The Complete Guide Bob Stayton http://www.sagehill.net/docbookxsl/ It has information about the transformation tools that may be used with Docbook XML (eg. xsltproc, xalan, saxon; fop, passivetex). Here's an extensive FAQ-style site: http://www.dpawson.co.uk/docbook/index.html Both Bob Stayton and Dave Pawson are luminaries on the docbook mailinglists. > The less tools we need the better. Always true .. XML is a good choice, since you probably need XML tools anyway, and Python includes good XML support. j |
From: Bram M. <Br...@mo...> - 2003-07-31 09:49:48
|
Jean Jordaan wrote: > > I don't know the essential difference between SGML docbook and XML > > docbook. Can both be converted to nice HTML and PDF? > > They're meant to be equivalent to write with. Docbook XML can be > processed with more tools, and the XML stylesheets are under more > active development as far as I can tell. > > I'd recommend using the XML version. I suppose I'll be looking for a tool to do the conversion then. > Here is a book about the XSL stylesheets in particular: > DocBook XSL: The Complete Guide > Bob Stayton > http://www.sagehill.net/docbookxsl/ > It has information about the transformation tools that may be used > with Docbook XML (eg. xsltproc, xalan, saxon; fop, passivetex). I attended a tutorial by Bob Stayton at OSCON. Clearly he knows what he is talking about, but unfortunately his presentation style wasn't very good. Starting with explaining how the tools work in detail, while you haven't seen any docbook file yet isn't a good idea. Only halfway he explained what <para> is used for... Anyway, thanks for the links, they can be helpful when I get stuck. > > The less tools we need the better. > > Always true .. XML is a good choice, since you probably need XML tools > anyway, and Python includes good XML support. XML is a nice format for computers, not for humans! -- hundred-and-one symptoms of being an internet addict: 28. You have comandeered your teenager's phone line for the net and even his friends know not to call on his line anymore. /// Bram Moolenaar -- Bram@Moolenaar.net -- http://www.Moolenaar.net \\\ /// Creator of Vim - Vi IMproved -- http://www.Vim.org \\\ \\\ Project leader for A-A-P -- http://www.A-A-P.org /// \\\ Help AIDS victims, buy here: http://ICCF-Holland.org/click1.html /// |
From: Jean J. <je...@up...> - 2003-07-31 10:11:32
|
Hi Bram > I suppose I'll be looking for a tool to do the conversion then. I don't *think* you need to change anything in the markup itself. Hopefully only the DOCTYPE at the top of the file. > XML is a nice format for computers, not for humans! Agreed, although writing DocBook XML is miles away from machine- oriented XML like SOAP. Bibliographies and complicated tables can get pretty hairy, but I found the markup was mostly quite light; lighter than HTML, certainly. You probably don't really need to write the docs directly in full-blown DocBook anyway. There are some alternatives. I'll list a couple. 1. StructuredText The Zope Book http://www.zope.org/Documentation/Books/ZopeBook/ is written in StructuredText and converted from there to DocBook, among other formats. Here is a very short recipe for converting STX to DocBook: http://vsbabu.org/mt/archives/2002/11/12/docbook_for_programmers.html Basically:: st=StructuredText.Basic(raw) doc=StructuredText.Document(st) html=StructuredText.HTML(doc) docbook = StructuredText.DocBookArticle(doc) Here is the Zope Book project at SourceForge: http://sourceforge.net/projects/zope-book http://cvs.zope.org/Packages/StructuredText/ There's another implementation of this idea, called reStructuredText. Here's an article about that, including mention of conversion to DocBook: http://www-106.ibm.com/developerworks/library/x-matters24/?ca=dnt-45 Going from DocBook -> StructuredText will be a bit of a pain, if you decide to go that route, certainly. But I think you'll like StructuredText. Do you know it? It's similar to the plaintext-with-conventions of the Vim helpfiles. 2. DocBook Lite DocBookLite is a DocBook subset. It's used by O'Reilly to format its books. It is also used by the subversion project. http://www.docbook.org/wiki/moin.cgi/DocBookLite -- Jean Jordaan http://www.upfrontsystems.co.za |
From: Bram M. <Br...@mo...> - 2003-07-31 13:55:24
|
Jean Jordaan wrote: > > I suppose I'll be looking for a tool to do the conversion then. > > I don't *think* you need to change anything in the markup itself. > Hopefully only the DOCTYPE at the top of the file. That would save a lot of work, and I can try it out in a simple way. I'll still have to locate the XML DTD then. I'm using FreeBSD with KDE, perhaps it's already somewhere on my system... [PS: Dan Sharp already gave a URL that has these files] > > XML is a nice format for computers, not for humans! > > Agreed, although writing DocBook XML is miles away from machine- > oriented XML like SOAP. Bibliographies and complicated tables > can get pretty hairy, but I found the markup was mostly quite > light; lighter than HTML, certainly. > > You probably don't really need to write the docs directly in > full-blown DocBook anyway. There are some alternatives. I'll > list a couple. Well, these alternatives still require editing text in some kind of special format that makes you look in the docs about the detailed syntax. None of them is WYSIWYG. Using a restricted set of the docbook macros doesn't make it much simpler. -- Far out in the uncharted backwaters of the unfashionable end of the Western Spiral arm of the Galaxy lies a small unregarded yellow sun. Orbiting this at a distance of roughly ninety-eight million miles is an utterly insignificant little blue-green planet whose ape-descended life forms are so amazingly primitive that they still think digital watches are a pretty neat idea ... -- Douglas Adams, "The Hitchhiker's Guide to the Galaxy" /// Bram Moolenaar -- Bram@Moolenaar.net -- http://www.Moolenaar.net \\\ /// Creator of Vim - Vi IMproved -- http://www.Vim.org \\\ \\\ Project leader for A-A-P -- http://www.A-A-P.org /// \\\ Help AIDS victims, buy here: http://ICCF-Holland.org/click1.html /// |
From: Jean J. <je...@up...> - 2003-07-31 14:00:57
|
> Well, these alternatives still require editing text in some kind of > special format that makes you look in the docs about the detailed > syntax. None of them is WYSIWYG. The problem is that WYS isn't WYG either ... Where *you* see two headings, *Word* might see one Heading style line, and one Paragraph, font size 16, font weight bold. Both look exactly the same, they're meant to convey the same meaning, but they're different for processing purposes. For consistency, you'd still have to have docs detailing exactly what styles to use where. Would you regard Vim's helpfiles as requiring editing in some kind of special format? I certainly would, but I find the format very helpful and worthwhile to master, and not that exacting. Both StructuredText and reStructuredText look very like plain text, just with certain conventions, not more complicated than the helpfile format. Compare this: http://docutils.sourceforge.net/spec/pep-0258.html and this, the reStructuredText source: http://docutils.sourceforge.net/spec/pep-0258.txt Does that txt look like a pain to write to you? > Using a restricted set of the docbook macros doesn't make it > much simpler. The restricted set of tags does reduce the size of the reference you need to be familiar with. -- Jean Jordaan http://www.upfrontsystems.co.za |
From: Bram M. <Br...@mo...> - 2003-07-31 15:20:53
|
Jean Jordaan wrote: > > Well, these alternatives still require editing text in some kind of > > special format that makes you look in the docs about the detailed > > syntax. None of them is WYSIWYG. > > The problem is that WYS isn't WYG either ... Where *you* see two > headings, *Word* might see one Heading style line, and one Paragraph, > font size 16, font weight bold. Both look exactly the same, they're > meant to convey the same meaning, but they're different for > processing purposes. It's not difficult at all to use WYSIWYG in the correct way. Just use paragraphs with a meaningful style and use text properties like "userinput" instead of italic. The problem is, of course, that such a program does not appear to exist. Even though it would be perfectly possible to create it (Oce was creating it while I was working there, but it never hit the market). Nevertheless, quite often you just want to make text bold and not worry about how to name that kind of text. Or add a line break without starting a new paragraph (haven't figured out how to do that yet in docbook). Sometimes it's just the layout that matters. > Would you regard Vim's helpfiles as requiring editing in some kind > of special format? I certainly would, but I find the format very > helpful and worthwhile to master, and not that exacting. True, but it's a format that is nearly impossible to convert to HTML or PDF, except by taking the text as-is, without reformatting. And a monospaced font needs to be used, otherwise columns of text are messed up. > Both StructuredText and reStructuredText look very like plain text, > just with certain conventions, not more complicated than the helpfile > format. Problem with these formats is it's even more difficult to mark pieces of text to be a specific kind. E.g., to specify that certain columns of text are part of a table. Especially something like: item1 this is a wrapped default value line explaining item1 in detail item2 something like that another value > Compare this: > http://docutils.sourceforge.net/spec/pep-0258.html > and this, the reStructuredText source: > http://docutils.sourceforge.net/spec/pep-0258.txt > > Does that txt look like a pain to write to you? Sure, looks quite nice. But what's the point? It's not what works, it's what _not_ works what matters. I don't see a table in this example. Can reStructuredText do nested tables? I need that. I might sound a bit frustrated, it appears too difficult to find good documentation tools that are easy to use. Perhaps it's my next project... > > Using a restricted set of the docbook macros doesn't make it > > much simpler. > > The restricted set of tags does reduce the size of the reference > you need to be familiar with. Hmm, I am currently familiar with a restricted set, but it may grow any moment. Why limit the growth? If you add some new tag it's easy to lookup what it does. It's the other way around that's complicated: wanting to add text in a certain structure and not knowing what tags to use. -- If they don't keep on exercising their lips, he thought, their brains start working. -- Douglas Adams, "The Hitchhiker's Guide to the Galaxy" /// Bram Moolenaar -- Bram@Moolenaar.net -- http://www.Moolenaar.net \\\ /// Creator of Vim - Vi IMproved -- http://www.Vim.org \\\ \\\ Project leader for A-A-P -- http://www.A-A-P.org /// \\\ Help AIDS victims, buy here: http://ICCF-Holland.org/click1.html /// |
From: Jean J. <je...@up...> - 2003-07-31 16:11:48
|
> It's not difficult at all to use WYSIWYG in the correct way. Just use > paragraphs with a meaningful style and use text properties like > "userinput" instead of italic. Yes, that's it. Programs even exist: isn't this what LyX purports to do? It even outputs DocBook. I think expensive things like Arbortext's Epic can also do wysiwyg docbook. http://www.lyx.org/ > Nevertheless, quite often you just want to make text bold and not worry > about how to name that kind of text. *emphasis*, **more emphasis**, in the StructuredText dialects .. > Or add a line break without > starting a new paragraph (haven't figured out how to do that yet in > docbook). Hmm, dunno either now .. > E.g., to specify that certain columns of > text are part of a table. Especially something like: > > item1 this is a wrapped default value > line explaining > item1 in detail > item2 something like that another value Yeah .. they have conventions to represent tables, but they do have limitations .. from the reStructuredText docs, http://docutils.sourceforge.net/spec/rst/reStructuredText.html#tables grid and simple tables: +------------------------+------------+----------+----------+ | Header row, column 1 | Header 2 | Header 3 | Header 4 | | (header rows optional) | | | | +========================+============+==========+==========+ | body row 1, column 1 | column 2 | column 3 | column 4 | +------------------------+------------+----------+----------+ | body row 2 | Cells may span columns. | +------------------------+------------+---------------------+ | body row 3 | Cells may | - Table cells | +------------------------+ span rows. | - contain | | body row 4 | | - body elements. | +------------------------+------------+---------------------+ ===== ===== col 1 col 2 ===== ===== 1 Second column of row 1. 2 Second column of row 2. Second line of paragraph. 3 - Second column of row 3. - Second item in bullet list (row 3, column 2). ===== ===== -- Jean Jordaan http://www.upfrontsystems.co.za |
From: Nikolai W. <lon...@ho...> - 2003-07-31 17:40:55
|
* Jean Jordaan <je...@up...> [Jul, 31 2003 18:30]: > > >Or add a line break without > >starting a new paragraph (haven't figured out how to do that yet in > >docbook). > > Hmm, dunno either now .. > This is impossible in DocBook (at the moment) to my knowledge, the reason, I guess, being that it has to do with layout, not content basically. As DocBook's purpose is to deal with the layout, not allow the user to do it. I agree however, that adding a line break has its merits ;-). I've been looking for this myself. nikolai -- ::: name: Nikolai Weibull :: aliases: pcp / lone-star ::: ::: born: Chicago, IL USA :: loc atm: Gothenburg, Sweden ::: ::: page: www.pcppopper.org :: fun atm: gf,lps,ruby,php,war3 ::: main(){printf(&linux["\021%six\012\0"],(linux)["have"]+"fun"-97);} |
From: Bram M. <Br...@mo...> - 2003-07-31 18:31:05
|
Jean Jordaan wrote: > > It's not difficult at all to use WYSIWYG in the correct way. Just use > > paragraphs with a meaningful style and use text properties like > > "userinput" instead of italic. > > Yes, that's it. Programs even exist: isn't this what LyX purports > to do? It even outputs DocBook. I think expensive things like > Arbortext's Epic can also do wysiwyg docbook. http://www.lyx.org/ I suppose LyX comes close. I should try it out when I have some time. Can it also read docbook files? I can't even find a reference to writing docbook on their site. If not, then I would need to redo all the documentation... -- How To Keep A Healthy Level Of Insanity: 3. Every time someone asks you to do something, ask if they want fries with that. /// Bram Moolenaar -- Bram@Moolenaar.net -- http://www.Moolenaar.net \\\ /// Creator of Vim - Vi IMproved -- http://www.Vim.org \\\ \\\ Project leader for A-A-P -- http://www.A-A-P.org /// \\\ Help AIDS victims, buy here: http://ICCF-Holland.org/click1.html /// |
From: Jean J. <je...@up...> - 2003-07-31 20:16:05
|
> I suppose LyX comes close. I should try it out when I have some time. That's what I also always think, but I was always disappointed. For me, nothing comes close to editing XML in Vim, with Stephen Riehm's bracketing macros :)) For me, this is also true of the various StructuredText options. I might write drafts in STX, just so that I can write w/o worrying about tags. But once the text has taken shape, I would prefer to generate DocBook from that and switch to editing the DocBook. The XML version will always be the richer version. For example, I would want to add an index at some point. With the XML version, I would go through the text adding <indexterm> tags, and the index will be generated automatically upon processing. From http://cyberelk.net/tim/docbook/selfdocbookx/indexing.html """ Adding an index to your document is easy; the DocBook XSL stylesheets=20 automatically cross-reference your tagged index words to generate the pag= e=20 numbers in the index section. For example, in the source XML of this docu= ment=20 you'll see that the index section at the end is indicated by just =93<ind= ex />=94. """ That's from another nice doc, by the way: "The Selfdocbook (XML edition) is a self-documenting introduction to DocBook DocBook (XML) book. It includes its own DocBook XML source in the appendix, and so can be used to learn DocBook by example." > Can it also read docbook files? I can't even find a reference to > writing docbook on their site. =20 Here's a HowTo: DocBook with LyX http://bgu.chez.tiscali.fr/doc/db4lyx/ From that: http://bgu.chez.tiscali.fr/doc/db4lyx/xml-overview.html#id270= 5103 """ Importing XML files To import XML file into LyX, you can use the DB2LyX set of stylesheets, t= hat=20 translate any XML file to a LyX-1.1.6 file compliant format. [...] LyX version 1.2.0 is expected to be able to export as XML DocBook, and = even=20 import an XML DocBook document. """ But like I said, I'm sticking with Vim :) --=20 Jean Jordaan http://www.upfrontsystems.co.za |
From: Bram M. <Br...@mo...> - 2003-07-31 21:27:16
|
Jean Jordaan wrote: Thanks for hints on how to make using docbook easier. I can edit the files with Vim without trouble, an essential improvement will have to come from not having to startup separate processing to view the results (and errors). Thus the hints to use docbook with LyX appear to be useful. I'll look into that later. > > Can it also read docbook files? I can't even find a reference to > > writing docbook on their site. > > Here's a HowTo: DocBook with LyX > http://bgu.chez.tiscali.fr/doc/db4lyx/ > > From that: http://bgu.chez.tiscali.fr/doc/db4lyx/xml-overview.html#id270= > 5103 > > """ > Importing XML files > > To import XML file into LyX, you can use the DB2LyX set of stylesheets, t= > hat=20 > translate any XML file to a LyX-1.1.6 file compliant format. [...] > LyX version 1.2.0 is expected to be able to export as XML DocBook, and = > even=20 > import an XML DocBook document. > """ -- How To Keep A Healthy Level Of Insanity: 15. Five days in advance, tell your friends you can't attend their party because you're not in the mood. /// Bram Moolenaar -- Bram@Moolenaar.net -- http://www.Moolenaar.net \\\ /// Creator of Vim - Vi IMproved -- http://www.Vim.org \\\ \\\ Project leader for A-A-P -- http://www.A-A-P.org /// \\\ Help AIDS victims, buy here: http://ICCF-Holland.org/click1.html /// |
From: Jean J. <je...@up...> - 2003-08-14 07:08:08
|
Further to this topic .. I've just seen an article about integrating DocBook into the Eclipse IDE: http://www.xml.com/lpt/a/2003/08/13/docbook-eclipse.html It documents a "working solution for transforming DocBook to Eclipse platform help". That article also references this one, which sounds good, and apropos for non-XML-fans ;) but which flaky DNS here doesn't let me see at the moment: Take My Advice: Don't Learn XML -- excellent introduction to DocBook and structured authoring by Michael Smith. -- Jean Jordaan http://www.upfrontsystems.co.za |
From: Adriaan de G. <ad...@cs...> - 2003-08-16 14:36:26
|
On Thursday 14 August 2003 08:58, Jean Jordaan wrote: > That article also references this one, which sounds good, > and apropos for non-XML-fans ;) but which flaky DNS here > doesn't let me see at the moment: > > Take My Advice: Don't Learn XML -- excellent introduction > to DocBook and structured authoring by Michael Smith. That one is at http://xml.oreilly.com/news/dontlearn_0701.html, and references Lauri's KDE docbook guide which I already promoted here. Yay. It's not so much an introduction to docbook as a statement that you should concentrate on learning the needed tools, not some random technology associated with the tool. In order to transform Docbook to something else, you'll need xsltproc. This can be provided by a libxslt package (/usr/ports/textproc/libxslt/ or obtained from the GNOME site). This will drag in libxml2 (again, in ports or from the GNOME site). Next, you need the Docbook DTD and XSL files. These can be obtained from the Docbook site, or are included with most KDE installations. As a convenience, I've tarred them up and put them up at http://www.cs.kun.nl/~adridg/docbook.tgz (290kb). The tarball unpacks a ./README.kde, along with directories xml-dtd-4.1.2/ and xsl/. It doesn't really matter where you put this stuff - /usr/local/share/docbook might be a good spot. I usually drop it in /tmp/docbook when I need it separately. Call the place where this tarball is unpacked $DOCBOOK_PREFIX. Next up, to convert XML docbook (say, exec.sgml) to HTML, you need to call xsltproc as follows: SGML_CATALOG_FILES=$DOCBOOK_PREFIX/xml-dtd-4.1.2/docbook.cat STYLESHEET=$DOCBOOK_PREFIX/xsl/html/chunk.xsl export SGML_CATALOG_FILES xsltproc --catalogs $STYLESHEET exec.sgml The required XML tag is <?xml version="1.0" ?> while the DOCTYPE tag is <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "dtd/docbookx.dtd" If you use the wrong DOCTYPE tag, you get a warning and the document is not checked against the DTD. -- pub 1024D/FEA2A3FE 2002-06-18 Adriaan de Groot <gr...@kd...> Key fingerprint = 934E 31AA 80A7 723F 54F9 50ED 76AC EE01 FEA2 A3FE |
From: Adriaan de G. <ad...@cs...> - 2003-07-31 19:37:32
|
On Thursday 31 July 2003 17:12, Bram Moolenaar wrote: > It's not difficult at all to use WYSIWYG in the correct way. Just use > paragraphs with a meaningful style and use text properties like > "userinput" instead of italic. That kind of semantic markup is important. It also requires you to document what kind of element gets what kind of tag when things aren't immediately obvious. For example, you use <literal> for all variable names. As far as that goes, I'd have to applaud \def\mysensiblesemanticlayoutitem#1{\textbf{#1}} and unfortunately, XML docbook doesn't support that in a straightforward way, since you need to hack the DTD among other things to do it. > The problem is, of course, that such a program does not appear to exist. > Even though it would be perfectly possible to create it (Oce was > creating it while I was working there, but it never hit the market). http://www.ipso-facto.demon.co.uk/development/xmelegance/xmelegance.html Although from the screenshots it seems development hasn't been recent. What looks like a maintained fork of that is http://apps.kde.com/na/2/info/id/1096 > Hmm, I am currently familiar with a restricted set, but it may grow any > moment. Why limit the growth? If you add some new tag it's easy to > lookup what it does. It's the other way around that's complicated: > wanting to add text in a certain structure and not knowing what tags to > use. [ugh, yet another KDE plug] I'd recommend the KDE docbook guide and (semi) tutorial, available at http://people.fruitsalad.org/lauri/markup/ (not really the official place, but I'm told it'll stick around there pretty much forever). If you're going to start writing an XML docbook file, this walks you through a fair amount of the boilerplate and also at least documents how one project has decided to map the docbook elements to local semantics. -- pub 1024D/FEA2A3FE 2002-06-18 Adriaan de Groot <gr...@kd...> Key fingerprint = 934E 31AA 80A7 723F 54F9 50ED 76AC EE01 FEA2 A3FE |
From: Adriaan de G. <ad...@cs...> - 2003-07-31 19:37:35
|
On Thursday 31 July 2003 17:12, Bram Moolenaar wrote: > I might sound a bit frustrated, it appears too difficult to find good > documentation tools that are easy to use. Perhaps it's my next > project... A help - one that understands XML and DTDs, and can at least suggest to you= =20 what a legal tag is in a given context - is the XML tools plugin for kate.= =20 Since Bram already has KDE on his system, kate is there too. It's not exact= ly=20 compatible with vim, though (although kvim exists too, and I believe work i= s=20 underway to make it a KTextEditor implementation, so that you can plug it=20 into the kate shell as well). The plugin, unfortunately, is in kdeaddons - = I=20 don't think there's a port for that, though. I can provide a tarball if=20 needed. =46rom other docbook folks: "jedit is worth a try, if you're editor agnosti= c, I=20 was quite impressed with it, it's got lots of lookup and autocomplete stuff= ,=20 but a bit tricky to get it working with the right DTD's." And that said, this thread is heading towards bikeshed territory, and I'm=20 going on vacation (with a book on Python programming in my suitcase, so I c= an=20 learn how to fix AAP bugs in future). =2D-=20 pub 1024D/FEA2A3FE 2002-06-18 Adriaan de Groot <gr...@kd...> Key fingerprint =3D 934E 31AA 80A7 723F 54F9 50ED 76AC EE01 FEA2 A3FE |
From: Adriaan de G. <ad...@cs...> - 2003-07-30 21:04:28
|
On Wednesday 30 July 2003 21:44, Bram Moolenaar wrote: > I don't know the essential difference between SGML docbook and XML > docbook. Can both be converted to nice HTML and PDF? Are both There is no essential difference. The DTDs are the same. Both can be converted to nice HTML (I know you don't use KDE, but you should take a look at its help:/ docs sometime - XML docbook, converted to HTML and with a fancy stylesheet applied to it, on the fly). The biggest change is that in XML, you need to watch you closing tags better. FWIW, I've already converted all the docs to XML for home use, and use xsltproc /usr/local/kde-3.1/share/apps/ksgmltools2/docbook/xsl/html/chunk.xsl exec.sgml to use the KDE stylesheets to divide the docbook into one html file per chapter; it looks pretty much exactly like your HTML files. > documented properly? I have been using the on-line version of the > O'Reilly book: http://www.docbook.org/tdg/en/html/docbook.html . It Yes, the same docbook works for both. I'd point you to the KDE docbook tutorial and guide, but the server it was on is dead right now. > The less tools we need the better. Then XML docbook is probably the cheapo way to go. Since XML docbook is also SGML, you can still use jade to produce PDF output (or use html2pdf, or FOP, which I've heard produces really nice output but requires a lot of java and TeX tweaking). -- pub 1024D/FEA2A3FE 2002-06-18 Adriaan de Groot <gr...@kd...> Key fingerprint = 934E 31AA 80A7 723F 54F9 50ED 76AC EE01 FEA2 A3FE |
From: Bram M. <Br...@mo...> - 2003-07-31 09:33:26
|
Adriaan de Groot wrote: > On Wednesday 30 July 2003 21:44, Bram Moolenaar wrote: > > I don't know the essential difference between SGML docbook and XML > > docbook. Can both be converted to nice HTML and PDF? Are both > > There is no essential difference. The DTDs are the same. Both can be > converted to nice HTML (I know you don't use KDE, but you should take > a look at its help:/ docs sometime - XML docbook, converted to HTML > and with a fancy stylesheet applied to it, on the fly). The biggest > change is that in XML, you need to watch you closing tags better. > FWIW, I've already converted all the docs to XML for home use, and use > > xsltproc /usr/local/kde-3.1/share/apps/ksgmltools2/docbook/xsl/html/chunk.xsl > exec.sgml > > to use the KDE stylesheets to divide the docbook into one html file per > chapter; it looks pretty much exactly like your HTML files. That sounds simpler than what I use now. Perhaps also faster? I don't like the idea of having to install KDE 3.1 just for this. Is the file available separately? And does it work when just obtaining that chunk.xsl file or are other files included from it? By the way, how did you convert the documentation from SGML to XML? -- hundred-and-one symptoms of being an internet addict: 26. You check your mail. It says "no new messages." So you check it again. /// Bram Moolenaar -- Bram@Moolenaar.net -- http://www.Moolenaar.net \\\ /// Creator of Vim - Vi IMproved -- http://www.Vim.org \\\ \\\ Project leader for A-A-P -- http://www.A-A-P.org /// \\\ Help AIDS victims, buy here: http://ICCF-Holland.org/click1.html /// |
From: Dan S. <dw...@ho...> - 2003-07-31 11:38:13
|
Bram Moolenaar wrote: > Adriaan de Groot wrote: > >>FWIW, I've already converted all the docs to XML for home use, and use >> >> xsltproc /usr/local/kde-3.1/share/apps/ksgmltools2/docbook/xsl/html/chunk.xsl >>exec.sgml >> >>to use the KDE stylesheets to divide the docbook into one html file per >>chapter; it looks pretty much exactly like your HTML files. > > I don't like the idea of having to install KDE 3.1 just for this. Is > the file available separately? And does it work when just obtaining > that chunk.xsl file or are other files included from it? It looks like it is just using the DocBook XSL stylesheets (from the docbook/xsl/html/chunk.xsl part of the command). You can get those from http://sourceforge.net/project/showfiles.php?group_id=21935 > By the way, how did you convert the documentation from SGML to XML? When I first started working on my Vim HOWTO, I had to use the SGML tools under Linux but used the XML tools in Windows. The only conversion I had to do from SGML -> XML was to add <?xml version="1.0"?> as the first line above the DOCTYPE, and change the DOCTYPE itself to V4.2, since that is what the XML stuff was written to use. I also had to add the DTD to the DOCTYPE, but I don't know if that was specific to the tool I use or not. Basically, my first line went from <!doctype article PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [ <!-- Entity list --> ]> to <?xml version="1.0"?> <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.2//EN" "../../dtd/docbookx.dtd" [ <!-- Entity list --> ]> Dan Sharp |
From: Bram M. <Br...@mo...> - 2003-07-31 15:30:36
|
Dan Sharp wrote: > Bram Moolenaar wrote: > > Adriaan de Groot wrote: > > > >>FWIW, I've already converted all the docs to XML for home use, and use > >> > >> xsltproc /usr/local/kde-3.1/share/apps/ksgmltools2/docbook/xsl/html/chunk.xsl > >>exec.sgml > >> > >>to use the KDE stylesheets to divide the docbook into one html file per > >>chapter; it looks pretty much exactly like your HTML files. > > > > I don't like the idea of having to install KDE 3.1 just for this. Is > > the file available separately? And does it work when just obtaining > > that chunk.xsl file or are other files included from it? > > It looks like it is just using the DocBook XSL stylesheets (from the > docbook/xsl/html/chunk.xsl part of the command). You can get those from > http://sourceforge.net/project/showfiles.php?group_id=21935 OK, I downloaded docbook-xsl-1.61.3.tar.gz and unpacked it. Hmm, that's a whole bunch of files. I can find the html/chunk.xsl file in there. > > By the way, how did you convert the documentation from SGML to XML? > > When I first started working on my Vim HOWTO, I had to use the SGML > tools under Linux but used the XML tools in Windows. The only > conversion I had to do from SGML -> XML was to add > > <?xml version="1.0"?> > > as the first line above the DOCTYPE, and change the DOCTYPE itself to > V4.2, since that is what the XML stuff was written to use. I also had > to add the DTD to the DOCTYPE, but I don't know if that was specific to > the tool I use or not. > > Basically, my first line went from > > <!doctype article PUBLIC "-//OASIS//DTD DocBook V4.1//EN" > [ > <!-- Entity list --> > ]> > > to > > <?xml version="1.0"?> > <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.2//EN" > "../../dtd/docbookx.dtd" > [ > <!-- Entity list --> > ]> OK, did that and moved the <?xml thing to before the first comment to get rid of an obvious error. Without the "docbookx.dtd" thing I'm getting lots of errors. Thus I suppose I need to add that line. But where do I find this file? It's not in the archive mentioned above. -- For a moment, nothing happened. Then, after a second or so, nothing continued to happen. -- Douglas Adams, "The Hitchhiker's Guide to the Galaxy" /// Bram Moolenaar -- Bram@Moolenaar.net -- http://www.Moolenaar.net \\\ /// Creator of Vim - Vi IMproved -- http://www.Vim.org \\\ \\\ Project leader for A-A-P -- http://www.A-A-P.org /// \\\ Help AIDS victims, buy here: http://ICCF-Holland.org/click1.html /// |
From: Adriaan de G. <ad...@cs...> - 2003-07-31 18:58:07
|
On Thursday 31 July 2003 11:24, Bram Moolenaar wrote: > > to use the KDE stylesheets to divide the docbook into one html file per > > chapter; it looks pretty much exactly like your HTML files. > > That sounds simpler than what I use now. Perhaps also faster? real 0m7.563s user 0m7.177s sys 0m0.079s on my Athlon XP 1600 ; certainly not enough time to fetch a new cup of tea. > I don't like the idea of having to install KDE 3.1 just for this. Is > the file available separately? And does it work when just obtaining > that chunk.xsl file or are other files included from it? Those files are just the standard docbook stylesheets, I'm told. Otherwise we can tar up the KDE ones separately (and the same stylesheets are in KDE < 3.1, just possibly with a different docbook revision). > By the way, how did you convert the documentation from SGML to XML? emacs + psgml did some work, and the rest was by hand because of missing and unbalanced tags and improperly closed empty elements. I'll send you the converted SGML files privately. The unbalanced tags needed to be fixed _anyway_, if you wanted real SGML and not the forgiving type. I'll see what KDE's docs writers use - they must have _something_ that helps them keep their tags balanced. -- pub 1024D/FEA2A3FE 2002-06-18 Adriaan de Groot <gr...@kd...> Key fingerprint = 934E 31AA 80A7 723F 54F9 50ED 76AC EE01 FEA2 A3FE |
From: Bram M. <Br...@mo...> - 2003-07-31 20:41:14
|
Adriaan de Groot wrote: > > That sounds simpler than what I use now. Perhaps also faster? > > real 0m7.563s > user 0m7.177s > sys 0m0.079s Jade takes a bit longer (but it works, and I didn't get xsltproc to work yet!). > > I don't like the idea of having to install KDE 3.1 just for this. Is > > the file available separately? And does it work when just obtaining > > that chunk.xsl file or are other files included from it? > > Those files are just the standard docbook stylesheets, I'm told. > Otherwise we can tar up the KDE ones separately (and the same > stylesheets are in KDE < 3.1, just possibly with a different docbook > revision). Dan Sharp pointed out where I could download the files needed. > > By the way, how did you convert the documentation from SGML to XML? > > emacs + psgml did some work, and the rest was by hand because of missing and > unbalanced tags and improperly closed empty elements. I'll send you the > converted SGML files privately. The unbalanced tags needed to be fixed > _anyway_, if you wanted real SGML and not the forgiving type. I did a few and mostly it's OK, but I have a problem with: <colspec colname='c2'/> I get an error for that. Any idea how this can be made to work with Jade? I thought the </> things were OK for SGML. Apparently they are not for XML. -- How To Keep A Healthy Level Of Insanity: 14. Put mosquito netting around your work area. Play a tape of jungle sounds all day. /// Bram Moolenaar -- Bram@Moolenaar.net -- http://www.Moolenaar.net \\\ /// Creator of Vim - Vi IMproved -- http://www.Vim.org \\\ \\\ Project leader for A-A-P -- http://www.A-A-P.org /// \\\ Help AIDS victims, buy here: http://ICCF-Holland.org/click1.html /// |
From: Adriaan de G. <ad...@cs...> - 2003-07-31 21:48:44
|
On Thursday 31 July 2003 22:41, Bram Moolenaar wrote: > Jade takes a bit longer (but it works, and I didn't get xsltproc to > work yet!). Like I said, I have all those things installed for KDE stuff, and it seems invisible and automatic to me. You mentioned you have KDE on your workstation - you just might look for this stuff in /usr/local, since I'm pretty sure all the stylesheets and stuff get installed with kdelibs. > I did a few and mostly it's OK, but I have a problem with: > > <colspec colname='c2'/> > > I get an error for that. Any idea how this can be made to work with > Jade? Try <colspec colanem="c2"></colspec>. That's valid XML, and probably valid SGML too. -- pub 1024D/FEA2A3FE 2002-06-18 Adriaan de Groot <gr...@kd...> Key fingerprint = 934E 31AA 80A7 723F 54F9 50ED 76AC EE01 FEA2 A3FE |
From: Bram M. <Br...@mo...> - 2003-08-01 10:10:50
|
Adriaan de Groot wrote: > > I did a few and mostly it's OK, but I have a problem with: > > > > <colspec colname='c2'/> > > > > I get an error for that. Any idea how this can be made to work with > > Jade? > > Try <colspec colanem="c2"></colspec>. That's valid XML, and probably valid > SGML too. Nope: jade:ref-commands.sgml:16:54:E: end tag for element "COLSPEC" which is not open -- How To Keep A Healthy Level Of Insanity: 17. When the money comes out the ATM, scream "I won!, I won! 3rd time this week!!!!!" /// Bram Moolenaar -- Bram@Moolenaar.net -- http://www.Moolenaar.net \\\ /// Creator of Vim - Vi IMproved -- http://www.Vim.org \\\ \\\ Project leader for A-A-P -- http://www.A-A-P.org /// \\\ Help AIDS victims, buy here: http://ICCF-Holland.org/click1.html /// |