From owner-freebsd-doc@FreeBSD.ORG Thu Apr 23 05:04:31 2009 Return-Path: Delivered-To: freebsd-doc@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34]) by hub.freebsd.org (Postfix) with ESMTP id 232E0106564A; Thu, 23 Apr 2009 05:04:31 +0000 (UTC) (envelope-from minimarmot@gmail.com) Received: from ey-out-2122.google.com (ey-out-2122.google.com [74.125.78.24]) by mx1.freebsd.org (Postfix) with ESMTP id 6F7E98FC08; Thu, 23 Apr 2009 05:04:30 +0000 (UTC) (envelope-from minimarmot@gmail.com) Received: by ey-out-2122.google.com with SMTP id 9so83189eyd.7 for ; Wed, 22 Apr 2009 22:04:29 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=gamma; h=domainkey-signature:mime-version:received:in-reply-to:references :date:message-id:subject:from:to:cc:content-type :content-transfer-encoding; bh=wGi//ugwtI+UJsYYN/RDrdN/u2Efx9+2Xp/qvkAcTks=; b=YuZZFRgX4XFsGRB6sTd11Y+/9ODtmsAsh9TpDK3bPD599WPJV5vkLhjiOUlghK9ywg 9OXyDJQofDbbdBPsvucE7TzFJPBrjlS6imtU1gBp0Jr9MFmeifwHohGE02hzsfgtgRJ4 70UIMoGg9TplpbFa+3Rw8zrDIicbuCnFSyAeg= DomainKey-Signature: a=rsa-sha1; c=nofws; d=gmail.com; s=gamma; h=mime-version:in-reply-to:references:date:message-id:subject:from:to :cc:content-type:content-transfer-encoding; b=e+Q481Untj5BEOL5vRvXhSHWuVgvMT0H07k9G0R52cSEYgP2gsbeLDscPS3peio+Xf nmfRFANySWfk+K9jhbrp0OQNuy98y89jRY9NyN6cyq2iLgAXgw2BeJpqV6h61d22yv3T Pb5pKeod90zKx8VY8jNsoEET1FVZqSs6okbys= MIME-Version: 1.0 Received: by 10.210.127.10 with SMTP id z10mr5805247ebc.29.1240461667929; Wed, 22 Apr 2009 21:41:07 -0700 (PDT) In-Reply-To: <49E837A0.6060503@FreeBSD.org> References: <49E837A0.6060503@FreeBSD.org> Date: Thu, 23 Apr 2009 04:41:07 +0000 Message-ID: <47d0403c0904222141g3c99d217u1e90e9d47424563c@mail.gmail.com> From: Ben Kaduk To: Gabor PALI Content-Type: text/plain; charset=ISO-8859-1 Content-Transfer-Encoding: quoted-printable Cc: freebsd-doc@freebsd.org Subject: Re: [PATCH] A Handbook Section on Documentation Ports X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 23 Apr 2009 05:04:31 -0000 On Fri, Apr 17, 2009 at 8:02 AM, Gabor PALI 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: How to keep your documentation up to date with - CVSup. 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] + 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. + + 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 [...]" + documentation ports provided monthly for + every supported language by the &a.doceng;. These ports are + listed in the &os; Ports Collection, under the virtual + category named docs. + + Basically, this technique implements almost the same method + as CVSup 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. 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." + + + 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. + + + + Building and Installing Documentation Ports + + Organization of the documentation ports is as follows: + + + + There is a master port, misc/freebsd-doc-en 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. I don't think that "probably ...users" is necessary + + + + There is an all in one port, misc/freebsd-doc-all, and it + builds and installs all documentation in all available + languages. + + + + Finally, there is a slave port for + each translation, e.g.: misc/freebsd-doc-hu for the + Hungarian-language documents. All of them depend on the + master port, and are present only for the ease of + installation. + + + + To install a documentation port by source, issue the s/by/from/ + following commands (as root): + [snip] + + + WITH_PDF + + + Allows the build of the &adobe; Portable Document + Format, for use with &adobe; &acrobat.reader; or + Ghostscript + (article.pdf, or + book.pdf, as appropriate). (I use xpdf, but this text is fine.) + + [snip] + + Using Packages + + 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. + [snip] Thanks for writing these up! -Ben Kaduk