Re: Move the Handbook into source tree

On Tue, Sep 7, 2021 at 12:17 PM David Chisnall <theraven@freebsd.org> wrote:

> Hi,
>
> I think there are two conflated things here:
>
>   - Moving the handbook into the source tree.
>   - Creating branches in the handbook that track particular releases.
>
> The first one is largely irrelevant to anyone other than people
> contributing to the handbook, so I'll focus on the second:
>
> This is quite an easy way of having a per-release snapshot but it means
> that the handbook will diverge for different releases over time.  If the
> new docs are documenting things that are new, that's fine, but if new
> docs are added to -CURRENT for things in a release, then they will need
> to follow the same MFC process as code flowing from current to releases,
> which brings up the potential of merge conflicts and so on.
>
> This is made even more complex in cases where code is MFC'd.  Typically
> (unfortunately) docs are added to the handbook after a feature is
> committed and so things will need to be MFC'd at the same time as other
> features are MFC'd or later if they're written after the original MFC.
>
> I see two possible workflows, the current and the proposed one, both of
> which have disadvantages:
>
>   - With the current workflow, you need to explicitly track which
> release things apply to in the document.
>   - With your proposed workflow, you need to explicitly track which
> release things apply to by merging them at the correct time.
>
> It's not clear to me that either of these is necessarily easier than the
> other.
>
> David
>
>



My primary training is "Mathematics ( Option : Statistics and Operations
Research ) , then Computer Engineering and Sciences .

https://en.wikipedia.org/wiki/Operations_research
Operations research

When we think in this context , propositions are ( NOT EXACT ) but as
alternatives or an alternative .
It is possible to think of moving the Handbook into the source tree because
manual pages are within the source tree .
It may even be possible to construct some parts of the Handbook by
utilizing the manual pages . In that way , errors due to
repetitions will be eliminated easily .

Therefore the main problem is not the way of the implementation of separate
handbooks but maintaining separate handbooks and
achieving correct and usable information in them . My proposition is also
considering "branching" of a new release .
If the Handbook is directly within the source tree or it is coupled into it
in such a way that branching covers it .


I think implementers will make their own decisions in the best way to
realize it successfully and easily .


Mehmet Erol Sanliturk








> On 07/09/2021 08:01, Mehmet Erol Sanliturk wrote:
> > Dear All ,
> >
> > in many of my messages to FreeBSD mailing lists I am mentioning the
> > following view :
> >
> >    "Please move the Handbook into source tree , and
> >     Maintain it with respect to current release without mixing sliding
> > releases : If you do this ,
> >     maintenance of a correct Handbook is IMPOSSIBLE because maintenance
> of
> >     associated IF statements about releases .
> > "
> >
> > When we look at the following web pages , we see the following :
> >
> > https://www.freebsd.org/cgi/man.cgi
> > FreeBSD Manual Pages
> >
> > In the second box of  "All sections" line , there are lines about all of
> > the FreeBSD releases
> > with many more other systems .
> >
> > In spite of this , in the following page :
> >
> > https://docs.freebsd.org/en/books/handbook/
> > FreeBSD Handbook
> > The FreeBSD Documentation Project
> >
> >
> > "
> > Abstract
> >
> > Welcome to FreeBSD! This handbook covers the installation and day to day
> > use of
> > FreeBSD 13.0-RELEASE, FreeBSD 12.2-RELEASE and FreeBSD 11.4-RELEASE. ...
> > "
> >
> > A Handbook which ( for me , exactly , for the others , perhaps  ) with
> many
> > errors ...
> >
> >
> > I think that , it is NOT extraordinarily a difficult process to move the
> > Handbook into source
> > tree and maintaining it with respect to per release and insert into the
> > above web page a part
> > similar to the manual pages to display the requested Handbook with
> respect
> > to releases .
> > In the present case , previous handbooks are lost , because of the
> > difficulty of finding them .
> >
> > Thank you very much and my best wishes for you and humanity in these
> > pandemic days ...
> >
> >
> > Mehmet Erol Sanliturk
> >
>
>