GNU bug report logs - #68963
30.0.50; [PATCH] Split Eshell built-in command documentation into subsections

Previous Next

Package: emacs;

Reported by: Jim Porter <jporterbugs <at> gmail.com>

Date: Wed, 7 Feb 2024 00:04:01 UTC

Severity: normal

Tags: patch

Found in version 30.0.50

Done: Jim Porter <jporterbugs <at> gmail.com>

Bug is archived. No further changes may be made.

Full log


View this message in rfc822 format

From: Jim Porter <jporterbugs <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: stefankangas <at> gmail.com, 68963 <at> debbugs.gnu.org
Subject: bug#68963: 30.0.50; [PATCH] Split Eshell built-in command documentation into subsections
Date: Thu, 8 Feb 2024 12:30:46 -0800
[Message part 1 (text/plain, inline)]
On 2/7/2024 11:07 PM, Eli Zaretskii wrote:
> I'm not against subdividing that section.  My point was that if you
> want these commands to be easier to find, the subdivision itself is
> not enough; you need additional measures.

I think you and Stefan have successfully convinced me that there's no 
need to try and fuss with making arbitrary divisions of the built-in 
commands. It's tricky to split them up just right, and time spent on 
that should go towards adding indexing instead.

> No objections here.  But once again: your points about being able to
> find the commands by categories are well-taken, and adding indexing to
> make that easier would also be a good change.

Attached are some initial improvements to the indexing (patch 0003 in 
the series). It would probably be worth adding concept indices to 
most/all of the built-in commands, but the few I added here are pretty 
straightforward, and I can just poke at this a bit at a time for the 
remainder. (Writing documentation isn't the most viscerally exciting 
thing to do, so I prefer to spread the work out.)

I also added patch 0002, which moves the indexing above the "@item"s. 
That way, when you navigate to the entry from the index, it shows the 
header line listing the supported arguments when viewing the 
documentation as HTML.
[0001-Put-the-list-of-built-in-Eshell-commands-in-its-own-.patch (text/plain, attachment)]
[0002-In-Eshell-manual-put-command-index-anchors-above-the.patch (text/plain, attachment)]
[0003-Add-concept-indices-for-some-Eshell-commands.patch (text/plain, attachment)]

This bug report was last modified 1 year and 127 days ago.

Previous Next


GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.