From owner-freebsd-hackers Tue May 22 9:34:48 2001 Delivered-To: freebsd-hackers@freebsd.org Received: from sj-msg-core-3.cisco.com (sj-msg-core-3.cisco.com [171.70.157.152]) by hub.freebsd.org (Postfix) with ESMTP id 2627137B43C; Tue, 22 May 2001 09:34:39 -0700 (PDT) (envelope-from bmah@cisco.com) Received: from bmah-freebsd-0.cisco.com (bmah-freebsd-0.cisco.com [171.70.84.42]) by sj-msg-core-3.cisco.com (8.11.3/8.9.1) with ESMTP id f4MGX3c03824; Tue, 22 May 2001 09:33:06 -0700 (PDT) Received: (from bmah@localhost) by bmah-freebsd-0.cisco.com (8.11.3/8.11.3) id f4MGYWa60632; Tue, 22 May 2001 09:34:32 -0700 (PDT) (envelope-from bmah) Message-Id: <200105221634.f4MGYWa60632@bmah-freebsd-0.cisco.com> X-Mailer: exmh version 2.4 05/15/2001 with nmh-1.0.4 To: "Karsten W. Rohrbach" Cc: freebsd-hackers@FreeBSD.ORG, freebsd-doc@FreeBSD.ORG Subject: Re: what is a good toolkit for multitarget documentation? In-Reply-To: <20010522144430.Q88529@mail.webmonster.de> References: <20010522144430.Q88529@mail.webmonster.de> Comments: In-reply-to "Karsten W. Rohrbach" message dated "Tue, 22 May 2001 14:44:30 +0200." From: "Bruce A. Mah" Reply-To: bmah@FreeBSD.ORG X-Face: g~c`.{#4q0"(V*b#g[i~rXgm*w;:nMfz%_RZLma)UgGN&=j`5vXoU^@n5v4:OO)c["!w)nD/!!~e4Sj7LiT'6*wZ83454H""lb{CC%T37O!!'S$S&D}sem7I[A 2V%N&+ X-Image-Url: http://www.employees.org/~bmah/Images/bmah-cisco-small.gif X-Url: http://www.employees.org/~bmah/ Mime-Version: 1.0 Content-Type: multipart/signed; boundary="==_Exmh_-124994816P"; micalg=pgp-sha1; protocol="application/pgp-signature" Content-Transfer-Encoding: 7bit Date: Tue, 22 May 2001 09:34:32 -0700 Sender: owner-freebsd-hackers@FreeBSD.ORG Precedence: bulk List-ID: List-Archive: (Web Archive) List-Help: (List Instructions) List-Subscribe: List-Unsubscribe: X-Loop: FreeBSD.ORG --==_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-hackers" in the body of the message