Date: Tue, 7 Sep 2021 13:49:14 +0300 From: Mehmet Erol Sanliturk <m.e.sanliturk@gmail.com> To: David Chisnall <theraven@freebsd.org> Cc: FreeBSD Current <freebsd-current@freebsd.org> Subject: Re: Move the Handbook into source tree Message-ID: <CAOgwaMsp7cPMTWQT5LZue%2B25KiKf-8Ub%2BSgrW9mrynncb87i=A@mail.gmail.com> In-Reply-To: <c8b8a994-c9c5-f664-9036-932fc3acc740@FreeBSD.org> References: <CAOgwaMs_H7mxuqCp2GOJtXhvZVpcC-go_9TtZ7uSeW_kmgNwHg@mail.gmail.com> <c8b8a994-c9c5-f664-9036-932fc3acc740@FreeBSD.org>
next in thread | previous in thread | raw e-mail | index | archive | help
--0000000000006e526305cb658635 Content-Type: text/plain; charset="UTF-8" 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 > > > > --0000000000006e526305cb658635--
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?CAOgwaMsp7cPMTWQT5LZue%2B25KiKf-8Ub%2BSgrW9mrynncb87i=A>