[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: Manual does not mention dictionary.el
From: |
Eli Zaretskii |
Subject: |
Re: Manual does not mention dictionary.el |
Date: |
Sat, 07 Dec 2024 09:27:27 +0200 |
> Date: Fri, 06 Dec 2024 22:14:26 +0300
> From: Jean Louis <bugs@gnu.support>
> CC: yandros@gmail.com
>
> >> For me, manuals (texinfo, man pages) are "the" definitive source for
> >> information about the installed features. Occasionally I use C-h a too,
> >> as it often catches things that are not mentioned in manuals.
> >
> >This is not the best practice for Emacs. The Emacs manuals don't
> >mention all the features, simply because there are too many of them,
> >and mentioning them all will make the manuals impractically large.
> >
> >By contrast, the built-in Help commands will return information about
> >all the features that are either already loaded or auto-loaded.
> >
>
> As an advocate for clarity and completeness, I believe the Emacs manual
> should encompass all features of Emacs.
This was never the practice in Emacs, and is basically infeasible.
The Emacs manuals are also printed and sold by the FSF shop, so they
must be of reasonable size. The ELisp manuals already prints in 2
volumes. (There are also manuals in doc/misc/, which document large
stand-alone features.)
> By definition, a manual is meant to provide comprehensive guidance, and
> leaving features undocumented goes against its purpose.
That some variable or command are not in the manual doesn't mean they
are "undocumented", because Emacs includes built-in documentation in
the form of doc strings.
> Emacs is a vast and powerful tool, and its users deserve a reference that
> covers every aspect of its functionality to truly harness its potential.
>
> We shall not look for size of manual to be "practical" while avoiding
> inclusion of useful features.
Again, this is not our policy here, and never has been.
And if you want to preach for fuller documentation, how about if you
start by volunteering to improve its coverage, by making sure every
new variable and function that are added to Emacs get properly
documented in the corresponding manuals? Because that particular
battlefield in the Emacs development is in sore need of dedicated
volunteers, and the maintainers alone cannot be expected to fill all
that void.
> But what do you mean, practical for what situation?
>
> Is it for printing maybe?
Yes.