Re: Future of groff Texinfo manual (was: documentation of hyphenation)

[Ingo Schwarze]

Hi James,

James K. Lowden wrote on Tue, Jun 30, 2020 at 09:45:17AM -0400:
> On Mon, 29 Jun 2020 20:36:31 +0200 Ingo Schwarze wrote:

>> I don't see any practical relevance to the question where exactly the
>> boundary between the "user manual" and the "reference manual" part
>> is.  

> I'm not sure what you're saying.

You quoted this out of context.

Branden said with his intended partial reorg, the Texinfo manual
would become the "tutorial" (i would rather call it "user manual"
in this case), and the man pages would become the "reference".

I answered it doesn't quite work that way because the meat of the
Texinfo manual, chapter 5, is the most important part of the
reference.

I also said that the following outcome of his scheme is just fine:

 1. The first few chapters of the Texinfo manual are written
    in user-manual style.
 2. The final chapter 5 of the Texinfo manual is the main GNU roff
    language reference.
 3. Most groff manual pages also form part of the the reference.

So regarding the format, 1 & 2 form a unit; but regarding the
content, 2 & 3 form a unit.  No real problem there, it's fine.
It doesn't matter where the boundary is.

> If you mean you don't know how you would divide the current text, OK.

I didn't say that, and i have no intention of diving any text.

> But surely you'd agree that there's
> a clear and useful distinction between a user guide that explains
> concepts and how to use the system incrementally, and one that provides
> the definitive explanation of how each component works, yes?  

Of course i have heard of the concept of having such a division,
but i no longer believe that it is important.  Ideally, when a system
is well-designed, you only need a refence manual, and in place of
a user manual, a few sentences at the beginning should suffice to
state the general purpose of the system.  But that opinion doesn't
matter in the context of groff because a substantial amount of text
written in user-manual style already exists, and nobody wants to
throw that text away in its entirety.

Yours,
  Ingo