having trouble making changes to the handbook

[Benjamin Kaduk]

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 at .)

> >> 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