From nobody Tue Sep 07 10:49:14 2021 X-Original-To: freebsd-current@mlmmj.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mlmmj.nyi.freebsd.org (Postfix) with ESMTP id 0CD7417A8BD2 for ; Tue, 7 Sep 2021 10:49:52 +0000 (UTC) (envelope-from m.e.sanliturk@gmail.com) Received: from mail-ua1-x929.google.com (mail-ua1-x929.google.com [IPv6:2607:f8b0:4864:20::929]) (using TLSv1.3 with cipher TLS_AES_128_GCM_SHA256 (128/128 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (2048 bits) client-digest SHA256) (Client CN "smtp.gmail.com", Issuer "GTS CA 1O1" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4H3hqM6hBdz3pC5; Tue, 7 Sep 2021 10:49:51 +0000 (UTC) (envelope-from m.e.sanliturk@gmail.com) Received: by mail-ua1-x929.google.com with SMTP id g2so5323737uad.4; Tue, 07 Sep 2021 03:49:51 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=mime-version:references:in-reply-to:from:date:message-id:subject:to :cc; bh=APKxKwY2oRB335uXudLuiZhm2fBTlAMxC0IE4rLL838=; b=UqwIWg+TaiK7aZ4CQF0fITVKJ2OxRl2hWm6DVR6/xdXJJBPHWO3cJYM3QW2H3ke+OS 1HMV+tzJRHwQTMllmdL/dB9hLV9K/BlA85sUJrn7CUR1zWV85VeOtQ01aUw1iVat6tLl OiXMDQ3wU4k3mSG3ECghTemmN1Fw7i4FTu1j5YWNRN9YVGkX0/umKiCfSq6SNX6JXZyR KjELv6w50D67qoeooMeaWk+dxA4MB2PVyQYrvYTFUvzgd0W3cDCfz+SgfXEfGL4TAAZe MLV2xthdNjFmJUSEh9mmhovkHB8ELLMi3JtfHuNbK3Mvz1G9xS+EI5/VzLCVLU0Nnu1+ V05g== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:mime-version:references:in-reply-to:from:date :message-id:subject:to:cc; bh=APKxKwY2oRB335uXudLuiZhm2fBTlAMxC0IE4rLL838=; b=Jk1YwSagizH9D2bFKx/fFXwTXC6/XlIFu673/W6lO90PB6ShsrqFy1fiKBoErCoa6U VzhcLRk1ucUudODQhhanT42Mx5WsueoNNdne1m8w5h7nx7rESKL9ldtxqBykT55zd2Do XEzVxOfrI4rL0yIK4kt/l5PZmi4ZenksxuvSw0EWOP8OrGbHuDo9c5uRYZm+aw7Tn+mh figXotRwBDF63jBPkRUZ1zh5yE2nj2pTHoEEMtI2/vzxWxZTI6v5rEB4/AxvEzU1wRlw wehHSlhVHFS+DXMcyHL1mqs4pgSV1EHI9qBLFrfZo5Hw9VLBBU7oPsvV1cdYIGbriAar KB8g== X-Gm-Message-State: AOAM532ufBB3iWVvEEdr4hv2I9SW+D1C8vooHInvSK7aq9ine76iRYym rqTLiT3lkq61Rb3LfAFdXHUS3RW0sk7u1DuwOJPW6TzuJag= X-Google-Smtp-Source: ABdhPJyacGxwPuuD3zSJQiwEAzoF/eCGU8ItoLgUWhaxKaLM4SN9KAgmHzeBbHCUsCqsQbmRh7GC+rppegnhfvr3x1o= X-Received: by 2002:ab0:1323:: with SMTP id g32mr7796391uae.63.1631011791064; Tue, 07 Sep 2021 03:49:51 -0700 (PDT) List-Id: Discussions about the use of FreeBSD-current List-Archive: https://lists.freebsd.org/archives/freebsd-current List-Help: List-Post: List-Subscribe: List-Unsubscribe: Sender: owner-freebsd-current@freebsd.org MIME-Version: 1.0 References: In-Reply-To: From: Mehmet Erol Sanliturk Date: Tue, 7 Sep 2021 13:49:14 +0300 Message-ID: Subject: Re: Move the Handbook into source tree To: David Chisnall Cc: FreeBSD Current Content-Type: multipart/alternative; boundary="0000000000006e526305cb658635" X-Rspamd-Queue-Id: 4H3hqM6hBdz3pC5 X-Spamd-Bar: ---- Authentication-Results: mx1.freebsd.org; none X-Spamd-Result: default: False [-4.00 / 15.00]; REPLY(-4.00)[]; TAGGED_FROM(0.00)[] X-Spam: Yes X-ThisMailContainsUnwantedMimeParts: Y --0000000000006e526305cb658635 Content-Type: text/plain; charset="UTF-8" On Tue, Sep 7, 2021 at 12:17 PM David Chisnall 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--