Date: Thu, 23 Apr 2009 04:41:07 +0000 From: Ben Kaduk <minimarmot@gmail.com> To: Gabor PALI <pgj@freebsd.org> Cc: freebsd-doc@freebsd.org Subject: Re: [PATCH] A Handbook Section on Documentation Ports Message-ID: <47d0403c0904222141g3c99d217u1e90e9d47424563c@mail.gmail.com> In-Reply-To: <49E837A0.6060503@FreeBSD.org> References: <49E837A0.6060503@FreeBSD.org>
next in thread | previous in thread | raw e-mail | index | archive | help
On Fri, Apr 17, 2009 at 8:02 AM, Gabor PALI <pgj@freebsd.org> wrote:
> Dear list members,
>
> In February, Marc Fonvieille (from the {Documentation,Release}
> Engineering Team) has finally committed some documentation ports to the
> FreeBSD ports tree (c.f. [1][2]), so I have provided some instructions
> on how to use them in the FreeBSD Handbook. =A0There is already an
> "Updating the Documentation Set" section, and I think adding further
> information on these documentation ports would be a good idea. =A0I do no=
t
> know whether the documentation ports are stable enough for common and
> everyday use, but while I wrote the patch I did not experience any
> problems with them.
>
> Feel free to review and comment on my patch [3].
>
> Thank you for your replies in advance, and already thanks rene@,
> manolis@, gabor@, trhodes@ for their initial comments and suggestions.
>
> Cheers,
> :g
>
> [1] http://www.freshports.org/docs
> [2] http://lists.freebsd.org/pipermail/freebsd-doc/2008-December/015088.h=
tml
> [3]
> http://people.freebsd.org/~pgj/patches/2009/04/12/documentation-ports.3.d=
iff
I appear to be a bit behind in my mail, but it looks like no one has
commented, and this still hasn't hit the tree ...
First off, this section (even before your patch) doesn't seem to make
any reference to csup, which is now in the base system.
I do think it's worth mentioning the documentation ports, and have
only a couple comments on the patch itself:
<listitem>
<para>How to keep your documentation up to date with
- <application>CVSup</application><!-- and
+ <application>CVSup</application>, or documentation ports<!--, and
<application>Docsnap</application>-->.</para>
</listitem>
This doesn't seem to have made it into the HTML preview that you linked
in your follow-up?
In any case, the comma is probably unnecessary.
@@ -959,6 +959,207 @@
[snip]
+ <para>In the previous section, we have presented a method for
+ updating the &os; documentation from sources. It required one
+ to install the documentation toolchain, check out the latest
+ source files, and rebuild them. This process is very similar to
+ rebuilding the world, i.e.: the &os; sources, and it can be a
+ bit cumbersome, and unnecessarily difficult.</para>
+
+ <para>An option to ease the process of documentation updating
+ while still staying close to the sources, is to use the
this line is a bit awkward. Perhaps "An easier way to update the
documentation while still using updated sources is to use the [...]"
+ <emphasis>documentation ports</emphasis> provided monthly for
+ every supported language by the &a.doceng;. These ports are
+ listed in the &os; Ports Collection, under the virtual
+ category named <ulink
+ url=3D"http://www.freshports.org/docs/">docs</ulink>.</para>;
+
+ <para>Basically, this technique implements almost the same method
+ as <application>CVSup</application> that we have already seen,
"that we have already seen" is redundant.
+ but here the entire process can be controlled by a simple
+ command, and compilation of the sources might be omitted as the
+ &os; package building cluster builds packages from the
+ documentation ports. Thus, the user can decide to update
+ documentation from a pre-built binary package.</para>
I think it might be better to say "and compilation of the sources
might be skipped through the use of a pre-built binary package
provided by the &os; package-building cluster."
+
+ <note>
+ <para>If building from sources is preferred, the mandatory
+ documentation tools will be automatically installed as a
I would s/mandatory documentation tools/tools needed to build the documenta=
tion/
+ dependency.</para>
+ </note>
+
+ <sect3 id=3D"doc-ports-install-make">
+ <title>Building and Installing Documentation Ports</title>
+
+ <para>Organization of the documentation ports is as follows:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>There is a <quote>master port</quote>, <filename
+ role=3D"package">misc/freebsd-doc-en</filename> where the
comma after freebsd-doc-en.
+ documentation port files can be found. It is the base of
+ all documentation ports. By default, it builds the
+ English documentation only, probably the most requested
+ language for the majority of the users.</para>
I don't think that "probably ...users" is necessary
+ </listitem>
+
+ <listitem>
+ <para>There is an <quote>all in one port</quote>, <filename
+ role=3D"package">misc/freebsd-doc-all</filename>, and it
+ builds and installs all documentation in all available
+ languages.</para>
+ </listitem>
+
+ <listitem>
+ <para>Finally, there is a <quote>slave port</quote> for
+ each translation, e.g.: <filename
+ role=3D"package">misc/freebsd-doc-hu</filename> for the
+ Hungarian-language documents. All of them depend on the
+ master port, and are present only for the ease of
+ installation.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>To install a documentation port by source, issue the
s/by/from/
+ following commands (as <username>root</username>):</para>
+
[snip]
+
+ <varlistentry>
+ <term><makevar>WITH_PDF</makevar></term>
+
+ <listitem>
+ <para>Allows the build of the &adobe; Portable Document
+ Format, for use with &adobe; &acrobat.reader; or
+ <application>Ghostscript</application>
+ (<filename>article.pdf</filename>, or
+ <filename>book.pdf</filename>, as appropriate).</para>
(I use xpdf, but this text is fine.)
+ </listitem>
+
[snip]
+ <sect3 id=3D"doc-ports-install-package">
+ <title>Using Packages</title>
+
+ <para>If resources are not available for the complete build and
+ installation of the documentation ports, or we simply want to
This sounds a bit awkward. "compilation" is perhaps not strictly
correct, so maybe "the complete process of building and installing the
documentation ports".
+ have the documentation installed in a more convenient way,
+ binary packages come handy. They can be managed as normal
s/come handy/are a convenient option/
+ &os; packages, via &man.pkg.add.1;, &man.pkg.delete.1;, and so
+ on.</para>
+
[snip]
Thanks for writing these up!
-Ben Kaduk
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?47d0403c0904222141g3c99d217u1e90e9d47424563c>