Date: Wed, 21 Feb 2001 15:35:01 -0500 (EST) From: Kenneth W Cochran <kwc@world.std.com> To: Nik Clayton <nik@freebsd.org> Cc: freebsd-stable@freebsd.org, freebsd-doc@freebsd.org Subject: Re: Tracking -docs like -stable Message-ID: <200102212035.PAA02577@world.std.com> References: <200102210104.UAA21183@world.std.com>
next in thread | previous in thread | raw e-mail | index | archive | help
>Date: Wed, 21 Feb 2001 16:56:17 +0000 >From: Nik Clayton <nik@freebsd.org> >To: Kenneth W Cochran <kwc@world.std.com> >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=<format> <target> > >where <format> 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... ><target> 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-doc" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?200102212035.PAA02577>