Date: Tue, 22 May 2001 09:34:32 -0700 From: "Bruce A. Mah" <bmah@FreeBSD.ORG> To: "Karsten W. Rohrbach" <karsten@rohrbach.de> Cc: freebsd-hackers@FreeBSD.ORG, freebsd-doc@FreeBSD.ORG Subject: Re: what is a good toolkit for multitarget documentation? Message-ID: <200105221634.f4MGYWa60632@bmah-freebsd-0.cisco.com> In-Reply-To: <20010522144430.Q88529@mail.webmonster.de> References: <20010522144430.Q88529@mail.webmonster.de>
next in thread | previous in thread | raw e-mail | index | archive | help
--==_Exmh_-124994816P Content-Type: text/plain; charset=us-ascii If memory serves me right, "Karsten W. Rohrbach" wrote: > i am currently evaluating different styles of implementing documentation > for some multiplatform software stuff. first i though about html only > docs, but this is not sufficient. then i thought about tex docs but this > wont work out either. > > the idea is to have a single 'master repo' style document tree that can > be used to dump out > - html all-in-one-file and chapters > - tex for pretty printing and pdf output > - man pages > - README, CHANGES and auxiliary documentation text files > > is sgml/docbook the way to go? i've seen that the freebsd handbook and > other documents obviously are written using the docbook dtd, but i > cannot find any pointers what software are involved in creating readable > documents. SGML and DocBook are *one* way to go to do this. It's pretty easy to do HTML, by-chapters HTML, PDF, PS, text, and a few other formats. You can build multiple renderings of a document (such as the Handbook) like this: % cd /usr/doc/en_US.ISO_8859-1/books/handbook % make 'FORMATS=html pdf txt' Yes, it's kind of complicated. Fortunately the FreeBSD Documentation Project infrastructure makes a lot of the pain go away. I'd browse around through the FreeBSD Documentation Project Primer for New Contributors, which is available at, among other places: http://www.freebsd.org/tutorials/docproj-primer/index.html Also look through the doc/ tree a little bit, in particular the Makefiles (look through some of the articles; they tend to be less complicated than the books). Note that if you have the doc/ tree and the textproc/ docproj meta-port installed, you can use a lot of the common Makefile stuff and you don't need to worry about the exact mechanics of how SGML gets turned into, for example, PDF. I'm working on a paper right now which has nothing to do with FreeBSD, but it uses a lot of the Makefile infrastructure from the FDP. Obviously this means I'd have some problems building on non-FreeBSD machines, but I don't consider that to be a huge problem at the moment. > another question is, if it is possible to 'fold' certain paragraphs or > whole chapters based on the assumption that we generate one handbook for > beginners and a slightly different one for advanced users and one with > source code snippets -- or even whole source files with annotations -- > for developers. Yes, you can do this in a couple of ways. One way is to do some conditional inclusion of text using SGML entities (see the section on using "INCLUDE" and "IGNORE" in marked sections in the FDP Primer...the copy I have shows it in section 3.8.1.2). Another way (which requires some stylesheet hacking) is to add some attribute support. RELNOTESng for -CURRENT does this for release note items that pertain only to specific architectures. I started this with marked sections as above, but decided to use attributes because we'll need its greater flexibility later. Hope this helps, Bruce. --==_Exmh_-124994816P Content-Type: application/pgp-signature -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.0.5 (FreeBSD) Comment: Exmh version 2.3.1+ 05/14/2001 iD8DBQE7CpUY2MoxcVugUsMRAuMCAJ4txFr2e1Wn8V3FaYQP7frHJDv2cwCcCvFY eoTK1ylHdiMe0SQi4sIkyL4= =QXkV -----END PGP SIGNATURE----- --==_Exmh_-124994816P-- To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?200105221634.f4MGYWa60632>