Date: Mon, 22 May 2017 21:48:53 -0500 From: Benjamin Kaduk <kaduk@mit.edu> To: Ernie Luzar <luzar722@gmail.com> Cc: FreeBSD questions <freebsd-questions@FreeBSD.org>, "freebsd-doc@freebsd.org" <freebsd-doc@FreeBSD.org> Subject: Re: having trouble making changes to the handbook Message-ID: <20170523024852.GV39245@kduck.kaduk.org> In-Reply-To: <59231887.7090100@gmail.com> References: <592041FB.9030408@gmail.com> <20170522050544.GS39245@kduck.kaduk.org> <59231887.7090100@gmail.com>
next in thread | previous in thread | raw e-mail | index | archive | help
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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20170523024852.GV39245>