From owner-freebsd-doc@freebsd.org Tue May 23 02:54:10 2017 Return-Path: Delivered-To: freebsd-doc@mailman.ysv.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) by mailman.ysv.freebsd.org (Postfix) with ESMTP id 239CAD799CF; Tue, 23 May 2017 02:54:10 +0000 (UTC) (envelope-from kaduk@mit.edu) Received: from dmz-mailsec-scanner-1.mit.edu (dmz-mailsec-scanner-1.mit.edu [18.9.25.12]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by mx1.freebsd.org (Postfix) with ESMTPS id AB4D4120F; Tue, 23 May 2017 02:54:09 +0000 (UTC) (envelope-from kaduk@mit.edu) X-AuditID: 1209190c-07dff70000001ef4-1a-5923a31ab765 Received: from mailhub-auth-2.mit.edu ( [18.7.62.36]) (using TLS with cipher DHE-RSA-AES256-SHA (256/256 bits)) (Client did not present a certificate) by dmz-mailsec-scanner-1.mit.edu (Symantec Messaging Gateway) with SMTP id 7F.08.07924.A13A3295; Mon, 22 May 2017 22:48:59 -0400 (EDT) Received: from outgoing.mit.edu (outgoing-auth-1.mit.edu [18.9.28.11]) by mailhub-auth-2.mit.edu (8.13.8/8.9.2) with ESMTP id v4N2mvhF013633; Mon, 22 May 2017 22:48:57 -0400 Received: from kduck.kaduk.org (24-107-191-124.dhcp.stls.mo.charter.com [24.107.191.124]) (authenticated bits=56) (User authenticated as kaduk@ATHENA.MIT.EDU) by outgoing.mit.edu (8.13.8/8.12.4) with ESMTP id v4N2mrM1030626 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NOT); Mon, 22 May 2017 22:48:56 -0400 Date: Mon, 22 May 2017 21:48:53 -0500 From: Benjamin Kaduk To: Ernie Luzar Cc: FreeBSD questions , "freebsd-doc@freebsd.org" Subject: Re: having trouble making changes to the handbook Message-ID: <20170523024852.GV39245@kduck.kaduk.org> References: <592041FB.9030408@gmail.com> <20170522050544.GS39245@kduck.kaduk.org> <59231887.7090100@gmail.com> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <59231887.7090100@gmail.com> User-Agent: Mutt/1.7.1 (2016-10-04) X-Brightmail-Tracker: H4sIAAAAAAAAA+NgFvrBIsWRmVeSWpSXmKPExsUixG6noiu9WDnSYOVLAYtTZ7pYLV5+3cRi cf30JHYHZo8Zn+azeOycdZc9gCmKyyYlNSezLLVI3y6BK2PzqotsBU2OFTc+pTYw7jTuYuTg kBAwkXi8KKiLkYtDSGAxk8Sqxm9sEM5GRokVy++yQzhXmSQunp3P3MXIycEioCpxb9c1VhCb TUBFoqH7MlhcBMjevOUpG4jNLFAs8aLxExOILSxgJfHqykqwGl6gbRP+fGQD2SwkUCTxuTsf IiwocXLmExaIVi2JG/9eMoGUMAtISyz/xwFicgpoStx4IQJSISqgLPH38D2WCYwCs5A0z0LS PAuheQEj8ypG2ZTcKt3cxMyc4tRk3eLkxLy81CJdQ73czBK91JTSTYygQOWU5NnBeOaN1yFG AQ5GJR5ejcdKkUKsiWXFlbmHGCU5mJREefckKEcK8SXlp1RmJBZnxBeV5qQWH2KU4GBWEuG9 sBAox5uSWFmVWpQPk5LmYFES55XQaIwQEkhPLEnNTk0tSC2CycpwcChJ8F4EaRQsSk1PrUjL zClBSDNxcIIM5wEaPg9seHFBYm5xZjpE/hSjLse7pR/eMwmx5OXnpUqJ875bAFQkAFKUUZoH NweUYCSy99e8YhQHekuY13MRUBUPMDnBTXoFtIQJaIn1M3mQJSWJCCmpBkY9BynNNNWNQWw3 JS8utr5yRojtSkpS1Zd10mv1av98nJStabbrzlce57evmV7olgQGzRZp4cvycFC6FJYS7z3/ 7t4/ahOLje9OSXsY2rVTmDP26Ydn3xq4Wea0X55++rdFvBXb7hPrFu7NT2ZiCRZkC+lVb205 ytxt9eB6vEvwVwHvNaWB95RYijMSDbWYi4oTAehKlAELAwAA X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 23 May 2017 02:54:10 -0000 On Mon, May 22, 2017 at 12:57:43PM -0400, Ernie Luzar wrote: > Benjamin Kaduk wrote: > > On Sat, May 20, 2017 at 09:17:47AM -0400, Ernie Luzar wrote: > >> I am following the info in this link > >> https://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/ > >> > >> I installed the textproc/docproj package. > >> > >> The above link says that svn is installed as part of that port. But it > >> really is not. Have to use the built in svnlite command. > > > > It seems that > > https://svnweb.freebsd.org/ports/head/textproc/docproj/Makefile?revision=420130&view=markup > > has some logic to not depend on devel/subversion when > > /usr/bin/svnlite is present in the build environment, which is > > arguably not the best choice, since the build environment need not > > match the install environment when pre-built packages are in use. > > > > > > The above reply makes no sense to me. svnlite is included in the base OS > release. So it's there in the build & install environment by default. > Are you trying to say the textproc/docproj port is in error and should > be fixed to install subversion as a dependent? The WITHOUT_SVNLITE src.conf(5) setting permits installing base without svnlite. (There is also a WITH_SVN to install svnlite as svn.) So, in WITHOUT_SVNLITE environments, at present, building textproc/docproj will pull in devel/subversion. I am suggesting that, given the number of other dependencies textproc/docproj has, adding devel/subversion unconditionally would not be that large of an incremnetal bloat, and would make things less confusing for people in a similar situation to you, as 'svn' would actually work right out of the box. > I used the OS default svnlite to checkout the whole doc tree and > manually updated the desired chapter source through creating the diff > file without any problems. > > Please expand and clarify your point. Does the above help? > > >> The shown command > >> "svnlite checkout https://svn.FreeBSD.org/doc/head ~/doc" > >> downloads far more items than wanted. This needs better example of just > >> downloading the desired language version of the handbook plus any > >> "shared directories" required for "make command" to work. How do I do this? > > > > It is intentionally undocumented, as there are multiple parts from > > the root needed to build a translation tree (in addition to the > > english sources, which are used when translations do not exist). > > No one has gone through to enumerate the list and commit to keeping > > it up to date as the build system changes. That is to say, you are > > free to attempt it, but it will require some investigation and it > > will probably be simpler overall to just accept the extra bytes as > > the cost of convenience. > > > > > > My post never voiced anything about the different translations of the > English version of the handbook. There is a separate doc on translations. > > My interpretation of your reply is that it is technicality possible to > checkout the desired handbook source based on language and them checkout > the parts of the master doc tree needed to "make" the html code version. > That to date, nobody has updated the > https://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/ > to include this information and I am free to do so. That is almost correct, in that I expect a submission to update the fdp-primer with the hypothetical instructions for this procedure would be rejected. (N.B. it is not my position to speak authoritatively on this matter, of course -- that would probably have to go to doceng@.) > >> I ran the "igor -R filename.xml | less -RS" command on the chapter I > >> wanted to work on before making any changes. To my surprise a bunch of > >> error are shown. Since these error are all already in the handbook > >> source I see no reason why I should try to correct them. > > > > Just because errors are preexisting they should be ignored instead > > of fixed? To be clear, no one is going to insist that you fix all > > issues in a file before adding content to it, but it is also a fine > > idea to make an initial cleanup patch before starting to do further > > work. > > > > As to how this situation might arise, the existing content is often > > quite old, and igor is a comparatively new tool (and continues to > > receive updates), so it is not surprising that there is old content > > that does not fully comply to the current standards. > > > > So "igor" is am independent application whose purpose is intended for > informational use only. It does not inhibit the flow of making changes. > It may be skipped all together. If something is really codded > incorrectly the "make" process will fail with very limited feedback > about the what it doesn't like and "igor" may used to help in the > investigation to fix the problem. That's correct. igor(1) is the brainchild of wblock@, and my memory feels like it's only a few years old, but then again time always passes faster than I think... > >> When I ran the "make" command the resulting html files are just written > >> into the directory that "make" was run from. How do I tell "make" to > >> write the output to a location of my selection? > > > > 'make install' should respect DESTDIR, of course, and I think (but > > did not test) that the usual OBJDIR-manipulation variables would > > work. > > > > I take this to mean there are existing methods to point the html code > generated by the make process to a separate path. Being brand new to > changing content of the handbook I am un-familiar with the DESTIR and > OBJDIR variables. > > Please provide an example of how to code it on the command line. `make DESTDIR=/path/to/web/root install` will install the compiled html files to the indicated path, but will also leave a copy of them in the source (doc?) tree where you currently don't like them. The one that I'm not entirely sure would work would be something like `make MAKEOBJDIRPREFIX=/usr/obj/doc` which I guess would mirror the directory structure of the doc tree checkout (using absolute paths!) inside /usr/obj/doc instead of leaving html files in the source tree. But again, I did not test that to check. MAKEOBJDIRPREFIX is documented in build(7). > >> What is really lacking is a way to view the changed output in a command > >> line browser. Installing a desktop just to view the changed handbook is > >> not an acceptable solution. > > > > But, what would the other location of your selection be that would > > be differently viewable in a command-line browser than the html > > files in the build tree? I generally use a browser (desktop or not) > > to view the html files next to the xml sources, which is usually > > "good enough" for what I need to do. > > > > > There is a very big difference between viewing the raw html or xml code > in a command line editor and what one sees when shown by a browser. The > ports system doesn't have a command line browser capable of displaying > the handbook content. I ftp the new generated html code to my ms/xp box > and view it using firefox. This method brings to light visual errors > that are syntax correct but not what you really wanted. It sounds like I misread the complaint, initially, then. The problem is that the compiled html is not very readable in any command-line browser, but I had interpreted your statement as meaning that it was too difficult to navigate to the html files in the build tree (?) and so having the generated html files in a different directory would help. Assuming you don't have a NFS or similar mount from your windows box of a filesystem on the FreeBSD machine, I don't know that there are substantially better options than ftp-ing like that. You could 'make install' to a staging area and only have to copy a subset of things, but that's not really much better, I think. > When I have complete knowledge of how to change the handbook I am > planing to update the fdp-primer incorporating this new information. > > Thank you Ben for you help and guidance. You're welcome; I hope we can get things set up and working well for you. -Ben