Re: Move the Handbook into source tree

On Tue, Sep 7, 2021 at 7:51 PM Wolfram Schneider <wosch@freebsd.org> wrote:

> We have 3 main repos: src, ports and doc. There are good reasons why
> we are doing this, and it will not change in the near future. For
> further questions and details, please ask on the freebsd-docs mailing
> list.
>
> You are right that the documentation on our web site is mostly for
> -current, the state of the art of the code base. If you need the
> documentation for our supported releases please check our
> Documentation Archive at
>
>  https://docs.freebsd.org/doc/
>
> and select your favourite release, e.g.
>
> the handbook for FreeBSD 13.0
>
> https://docs.freebsd.org/doc/13.0-RELEASE/usr/local/share/doc/freebsd/en/books/handbook/
>
> the handbook for FreeBSD 12.0
>
> https://docs.freebsd.org/doc/12.0-RELEASE/usr/local/share/doc/freebsd/en/books/handbook/
>
> -Wolfram
>
> On Tue, 7 Sept 2021 at 09:03, Mehmet Erol Sanliturk
> <m.e.sanliturk@gmail.com> 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
>
>
>

If you consider me , now at home  there is 4.4BSD Lite ( Version 2.0 .
Released Sept 1995 ) as a memorial .
I could not find any previous release because it is likely that I left them
in my university during my retirement to allow them to install them
in university student laboratories .

Trouble is NOT ME , because since 1970 I have been in the computing area (
starting my work since 1966 ) .


My PhD  thesis is
"A multimedia information management system ( 1995 )" getting two vetoes (
both of them being virtual ) , one PhD sufficiency examination because of
"This thesis proposition is in very much upper level with respect to a PhD
thesis requirements"  ,
another veto in thesis defense because
"We need to mention that , although this thesis is excellent , it is
impossible to complete it as a PhD thesis due to its very complicated
difficulty level .
If we do not mention this , later on , if anyone sees our  "Thesis defense
evaluation report" may say that
"How such a jury does not recognize the difficulty level of this thesis and
does not mention it ."  If all of you say "YES" , I will mention this
point and say "NO" , but if any one of you says "NO" , my vote is "YES" . "

They asked :
"How did you do it ?"   ... 'based on my vast experience and theoretical
works performed previously " ... ( my primary work area is "Theoretical
Computing Sciences" )
"Why did you not use simulation ? "  ... "for me , writing a simulator is
much more difficult than writing its  own implementation sufficient to show
its feasibility and usability ." ...



Then trouble is an unusable handbook due to many errors spreaded over it
due to its SLIDING nature of consisting of THREE separate releases .

You may say that "The discussion area is  in "docs" list . For me "NO" ,
because
"It is a FreeBSD System Design Problem, not a 'docs' problem " ,
because use of FreeBSD is based on use of a handbook , because FreeBSD is
not doing anything by itself  , the only user doing everything .
For this , the Handbook is a vital component for use of it .

When tracking the mailing lists ( I am one of them , nearly the start of
the Internet at least in my country Turkey ) mostly people are using it
based on their experience or by reading sources .
How can  WE acquire such an expertise or is it possible that everyone will
read the sources and use it ?

I have mentioned this point very long ago , and I am repeating this point
continuously without any tangible result .

This difficulty is driving FreeBSD to a very small user base and then
causing
prevention of acceptance by large masses .



I am not able to install FreeBSD due to its very complicated  install
system .
I am not able to use FreeBSD due to its uncomprehensible *.conf files and
incompatible KDE system ( for my needs . I do not use other ones because of
my needs ) . ...



There is a necessity to produce a ( usable , correct information containing
handbook ) because everything is based on descriptions .
It is not like Linux . I am installing Linux ( Fedora KDE , before Mandriva
) without using extra documentation . When it comes to FreeBSD , I am
maintaining a thickest folder filled with flash cards . A new release is
coming , requiring you to modify  these cards .
From where ? From the Handbook ?


Thank you very much .


Mehmet Erol Sanliturk









>
> --
> Wolfram Schneider <wosch@FreeBSD.org> https://wolfram.schneider.org
>