Opened 6 months ago

Last modified 5 days ago

#32621 new task

Add automated checks to make sure man page options stay in alphabetical order

Reported by: teor Owned by:
Priority: Medium Milestone: Tor: 0.4.4.x-final
Component: Core Tor/Tor Version:
Severity: Normal Keywords: documentation tor-client manpage easy 043-can
Cc: catalyst, swati Actual Points:
Parent ID: #4310 Points: 1
Reviewer: Sponsor:

Description

We should add automated checks or automated tooling that makes sure that the man page options are in alphabetical order (within sections).

These tools will help us not regress #4310.

Child Tickets

Change History (7)

comment:1 Changed 5 months ago by catalyst

I looked briefly at Python's diffutils library and it seems plausible as a basis for such a tool.

We'd need some easily-parsed way to mark exceptions, and maybe some way to double-check that the anchors names match their item names. (Also we should skip the "formatting only" anchors.)

comment:2 Changed 5 months ago by atagar

Stem provides a module to read tor's man page. Actually, we already have tests for its content...

https://gitweb.torproject.org/stem.git/tree/stem/manual.py
https://gitweb.torproject.org/stem.git/tree/test/integ/manual.py

If you'd care to check for alphabetization this is likely the best spot to do so.

comment:3 Changed 5 months ago by ahf

Keywords: 043-can added

comment:4 Changed 3 months ago by teor

If we're going to automate these checks, they should go in:

  • the make check target, and
  • the pre-commit git hook.

Since we can't be sure if stem is installed, it might be a good idea to avoid a dependency on stem.

If we do need to depend on stem, we should skip the tests (without failure) if stem is not installed.

comment:5 Changed 3 months ago by atagar

Hi teor. Sorry, unsure I follow - if a stem integ test it would be included under tor's stem testing target. Alphabetisation doesn't seem critical enough to warrant the hassle of a pre-commit hook but up to you folks.

comment:6 in reply to:  5 Changed 3 months ago by teor

Replying to atagar:

Hi teor. Sorry, unsure I follow - if a stem integ test it would be included under tor's stem testing target.

Yes, that's true, we run the stem tests in Tor's CI.

But we don't run them during "make check".

Alphabetisation doesn't seem critical enough to warrant the hassle of a pre-commit hook but up to you folks.

We have an existing pre-commit hook that runs most of our simple checks.

The final design is totally up to the author and reviewer. I think catalyst has been doing some work here, so I'm happy to leave it to them.

comment:7 Changed 5 days ago by nickm

Milestone: Tor: 0.4.3.x-finalTor: 0.4.4.x-final

0.4.3 was released: Move non merge-ready 0.4.3 tickets to 044.

Note: See TracTickets for help on using tickets.