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 Message-ID: <20010221165617.A5802@canyon.nothing-going-on.org> In-Reply-To: <200102210104.UAA21183@world.std.com>; from kwc@world.std.com on Tue, Feb 20, 2001 at 08:04:04PM -0500 References: <200102210104.UAA21183@world.std.com>
next in thread | previous in thread | raw e-mail | index | archive | help
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.
> After cvsup of doc-all, in what directory should I be when
> making/building?
Depends. If you've pulled down the whole repository you will need to
check out the doc/ hierarchy first, something like
% cd
% mkdir doc-cvs
% cd doc-cvs
% cvs -d /home/ncvs checkout doc
% cd doc
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.
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
(if you want to build multiple formats at once then you have to protect
the spaces from the shell, either something like
% make "FORMATS=html ps" ...
or
% make FORMATS=html\ ps ...
<target> should be one of
-blank- If you don't specify a target, or you specify
all a target called "all" then the document will be
converted to the FORMATS you list.
clean Removes the formatted document, and any
intermediate files created by the build process.
install Installs the document, typically somewhere under
/usr/share/doc -- this path is controlled by the
DOCDIR variable.
package Builds a FreeBSD package of the formatted
document that can be manipulated (installed,
queried, etc) with the FreeBSD pkg_* commands.
lint Both these targets will verify that the document
validate is valid according to the DTD it claims to
comply with.
> & 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.
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.
Hope that helps,
N
--
Internet connection, $19.95 a month. Computer, $799.95. Modem, $149.95.
Telephone line, $24.95 a month. Software, free. USENET transmission,
hundreds if not thousands of dollars. Thinking before posting, priceless.
Somethings in life you can't buy. For everything else, there's MasterCard.
-- Graham Reed, in the Scary Devil Monastery
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?20010221165617.A5802>