search

bitcoin / bitcoin

Bitcoin Core integration/staging tree
https://bitcoincore.org/en/download
MIT License
77.22k stars 35.64k forks source link

FILES section for man pages #29557

Open BebeSparkelSparkel opened 4 months ago

BebeSparkelSparkel commented 4 months ago

bitcoind and bitcoin-qt have a lot of files and it would be very helpful to have a FILES section, like most man pages have, that lists the files and directories with a short explanation of their purpose.

bitcoin-wallet should have the default wallet directory listed in the FILES section.

fanquake commented 4 months ago

Note that we currently have doc/files.md, which would be a starting point for something like this.

willcl-ark commented 4 months ago

I was thinking about this a little earlier and I'm not sure there is a single approach that I particularly like that I could think of. The issue I wanted to avoid was having manpages getting out of sync with doc/files.md (and with the binaries themselves).

This gives us a few options:

  1. Have the binaries' --help page output a files section to be parsed by help2man (lots of cpp changes needed. Not worth it IMO)
  2. We could change doc/files.md to use a particular markdown format which could be parsed by a tool like ronn, which can parse markdown into roff, then have a conversion take place and include that file into the help2man process. This markdown would look something like (the files section) here.
  3. We could just write the raw roff (looks like this), but then keeping things in sync becomes a pain without writing a test or something.
  4. Probably other ways I didn't consider...

Overall I think it's not worth the maintenance.

IMO we could add a FILES section with the default datadir and wallet dir, and reference doc/files.md file which is both in the source distribution and on github (but not in the binary distributions-- perhaps this could be changed?)