Doc: Fixup misplaced filelist.sgml entities and add some commentary
Hi.
Having been in filelist.sgml a bit recently I've noticed that the original
alphabetical ordering of the entities therein hasn't been adhered to.
Partly, I suspect, because there is no guidance about these files and how
they are organized. The attached puts things back into alphabetical order
(by section) and adds some commentary to this and related files, and the
manual.
I made the choice to move the special %allfiles; reference to the top since
placement doesn't matter and burying the one unique thing in the middle of
the file didn't seem helpful. Now both its immediate presence and the
comment point out the existence and purpose of ref/allfiles.sgml.
David J.
Attachments:
doc-reorder-entities-and-comment.difftext/x-patch; charset=US-ASCII; name=doc-reorder-entities-and-comment.diffDownload+109-50
Em qua., 19 de mar. de 2025 às 18:14, David G. Johnston <
david.g.johnston@gmail.com> escreveu:
Having been in filelist.sgml a bit recently I've noticed that the original
alphabetical ordering of the entities therein hasn't been adhered to.
Partly, I suspect, because there is no guidance about these files and how
they are organized. The attached puts things back into alphabetical order
(by section) and adds some commentary to this and related files, and the
manual.
Liked that.
Just one typo: chatpers should be chapters.
regards
Marcos
On Wed, Mar 19, 2025 at 2:31 PM Marcos Pegoraro <marcos@f10.com.br> wrote:
Em qua., 19 de mar. de 2025 às 18:14, David G. Johnston <
david.g.johnston@gmail.com> escreveu:Having been in filelist.sgml a bit recently I've noticed that the
original alphabetical ordering of the entities therein hasn't been adhered
to. Partly, I suspect, because there is no guidance about these files and
how they are organized. The attached puts things back into alphabetical
order (by section) and adds some commentary to this and related files, and
the manual.Liked that.
Just one typo: chatpers should be chapters.
Thanks.
I've got some additional thoughts for the next version; though I figure
this, and the others like it out there right now, won't get much attention
until mid-April.
Be better to do larger refactorings like this after feature freeze anyway.
We've tended to not consider the documentation part of what is frozen so
looking at it post-deadline makes sense.
David J.
Hi, David,
In the file docguide.sgml, there is a typo.
"Within the book are parts, mostly defined within the same file, expect
for the", the "expect" here should be "except".
Thanks,
Steven
在 2025/3/20 5:13, David G. Johnston 写道:
Show quoted text
Hi.
Having been in filelist.sgml a bit recently I've noticed that the
original alphabetical ordering of the entities therein hasn't been
adhered to. Partly, I suspect, because there is no guidance about these
files and how they are organized. The attached puts things back into
alphabetical order (by section) and adds some commentary to this and
related files, and the manual.I made the choice to move the special %allfiles; reference to the top
since placement doesn't matter and burying the one unique thing in the
middle of the file didn't seem helpful. Now both its immediate presence
and the comment point out the existence and purpose of ref/allfiles.sgml.David J.