From owner-freebsd-stable Wed Feb 21 12:35:17 2001 Delivered-To: freebsd-stable@freebsd.org Received: from sgi04-e.std.COM (sgi04-e.std.com [199.172.62.134]) by hub.freebsd.org (Postfix) with ESMTP id AC13B37B401; Wed, 21 Feb 2001 12:35:02 -0800 (PST) (envelope-from kwc@world.std.com) Received: from world.std.com (world-f.std.com [199.172.62.5]) by sgi04-e.std.COM (8.9.3/8.9.3) with ESMTP id PAA2690813; Wed, 21 Feb 2001 15:35:02 -0500 (EST) Received: (from kwc@localhost) by world.std.com (8.9.3/8.9.3) id PAA02577; Wed, 21 Feb 2001 15:35:01 -0500 (EST) Date: Wed, 21 Feb 2001 15:35:01 -0500 (EST) From: Kenneth W Cochran Message-Id: <200102212035.PAA02577@world.std.com> To: Nik Clayton Subject: Re: Tracking -docs like -stable Cc: freebsd-stable@freebsd.org, freebsd-doc@freebsd.org References: <200102210104.UAA21183@world.std.com> Sender: owner-freebsd-stable@FreeBSD.ORG Precedence: bulk X-Loop: FreeBSD.ORG >Date: Wed, 21 Feb 2001 16:56:17 +0000 >From: Nik Clayton >To: Kenneth W Cochran >Cc: freebsd-doc@freebsd.org, freebsd-stable@freebsd.org >Subject: Re: Tracking -docs like -stable > >Kenneth, >On Tue, Feb 20, 2001 at 08:04:04PM -0500, Kenneth W Cochran wrote: >> Hello -stable & -docs: >> >> I'm trying to "track" documentation similarly to -stable. >> I can cvsup the "docs-supfile" Just Fine, but what needs to >> be done afterward? > >Chapter 7 of the FDP Primer, at > > http://www.freebsd.org/tutorials/docproj-primer/ > >should help. Well, it does help some, but some of the text confuses me; example: Section 7.3 - "Make includes" - is "includes" a make-target or some kind of description? (I think it is a description/title, but it could be a target & I find the context somewhat confusing, sorry...) >> After cvsup of doc-all, in what directory should I be when >> making/building? > >Depends. If you've pulled down the whole repository ... Nope, no repository at this time... >Alternatively, if you've just pulled down the most current files then >you will have told CVSup where to put them, probably somewhere like >/usr/doc. Ah, this one... >If you want to build all the documentation, start at the root directory >of the checked out docs (e.g., /usr/doc/, or $HOME/doc-cvs/doc if you >follow the example above), and run make(1). > >If you want to build all the documentation for a specific language and >encoding, then cd(1) down a level, eg > > % cd en_US.ISO_8859-1 > >If you want to build all the articles, or books, for a specific language >then cd(1) down one more level > > % cd books > >or > > % cd articles > >If you want to build a specific document, such as the FAQ, cd(1) down in >to it's directory > > % cd faq > >before running make(1). > >> What are the relevant make-targets for documentation > >Typically, you will do something like this > > % make FORMATS= > >where is one or more of > html html-split txt ps pdf pdb rtf Is there a manifest constant for /etc/make.conf for these? I found one for languages & am using it... > should be one of {-blank-,all,clean,install,package,lint,validate} >> & where can I find them? > >Chapter 7 of the primer (in theory). I've just had a look at that, and >it's as enlightening as it could be. I would be very grateful for >submissions that cleaned it up. Your message to me with these descriptions explains it *much* better (to me) than the primer. Sorry, the Primer seems much too lengthy for *this* usage. As I mentioned previously, the Primer appears oriented to Authors, not sysadmins (ie. someone who only wants to Keep A System Up-To-Date (for the time being, until he learns how to author documents... :)). >If you just want to quickly check that a particular format builds you >can give the target filename. For example, > > % cd doc/en_US.ISO_8859-1/books/faq > % make book.html > >will generate the FAQ as one large HTML document. You could also do > > % make index.html # Lots of little HTML files > % make book.ps # Postscript > % make book.pdf # PDF > ... > >> How do I properly omit building the .pdf and .ps versions? > >Make sure that the FORMATS variable doesn't contain "pdf" or "ps". By >default, it doesn't. > >> I can't find anything in The Books (Lehey v3 & the >> Handbook) & the docproj Web-site seems targeted toward >> documentation "authors" & not toward documentation "trackers." >> >> The textproc/docproj port is installed. > >Incidentally, you will probably need to update this, as I committed some >changes to it last night, to pull in eps2png and the netpbm utilities, >which are required now that we support graphics in the documentation. Aaaaah... Oooops... :) >Hope that helps, > >N Ah, very much so! Thanks! I think something like this description/explanation would be a worthy addition to something like src/UPDATING. Hmmm, maybe "doc/UPDATING?" And with references to the respective "UPDATING" documentation in the "other" places? (For example, src/UPDATING containing a reference to doc/UPDATING & vice-versa.) -kc To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-stable" in the body of the message