generating TLDR md files from a TLDR section in the man page

[teuben]

I have my own package with some 400+ man pages (and growing). A lot of them have an EXAMPLES section, but they can be verbose, where perhaps a TLDR type structure could be something more useful for some more experienced users.

I'm thus wondering if I could add a TLDR section in the man page, which is formatted in such a way that a preprocessor could generate a series of md files for a tldr client (how the client can see them is another matter, see e.g. tldr-pages/tldr-node-client#239). Since a man page already has the name and synopsis, the only thing that is missing are the one line example description and the one line command syntax, e.g.

   .SH NAME
    command - this command does bla bla

   .SH TLDR
   Example description 1
   % command -opt1 -opt2 -arg1 {{arg_value}}

   Example description 2
   % command -opt1 -opt2

There was an earlier discussion on extracting tldr information from the EXAMPLES sections, see #1489 which may relate to my query.

In another issue the uniformity of clients, which was discussed in #4044

[sbrl]

Sounds like an interesting project! Are you planning on interfacing with the tldr-pages ecosystem in any way?

[bl-ue]

By the EXAMPLES do you mean the EXAMPLES section found here? Can you send an example of one of your pages?

The issue I see is putting the token syntax around the parameters — is there any way for a machine to tell what are considered variable parameters?

[teuben]

The ip-address example you showed is close to what I had in mind, mine would follow the TLDR standard a little closer (as sketched above). You can see the full example here: https://github.com/teuben/nemo/blob/master/man/man1/tsf.1

So in my example I'm considering keeping closer to the TLDR standard, to avoid issues like variable parameters. That does make reading the man page a little harder. Perhaps this could be worked out.

[teuben]

Sounds like an interesting project! Are you planning on interfacing with the tldr-pages ecosystem in any way?

The "man" command can be easily tailored , by hacking the MANPATH variable. But I do have a problem with tldr, as it may not see my personal tldr pages without a flag or hack. But that's client specific ;-(

[bl-ue]

Oh, I see. I was getting confused, thinking that you'd generate a tldr section in the man page. Then yeah, it would be a piece of cake to extract that out of a man page and into a markdown file!

[bl-ue]

(Holy cow, that repo is 34 years old!!! 🤪)

[teuben]

(Holy cow, that repo is 34 years old!!! zany_face)

and it's still buzzing :[) Well, unix time-stamps from 1986, CVS imported around 2000, converted to git in 2017. It was nice to see it preserved all those timestamps.
The other cool thing we do is the --help style, which reports the one line description per keyword. We have a python script that checks if the man page (which is a separate file after all) is in sync with what the binary knows.

[teuben]

Oh, I see. I was getting confused, thinking that you'd generate a tldr section in the man page. Then yeah, it would be a piece of cake to extract that out of a man page and into a markdown file!

yeah. I wasn't keen on having a 3rd file to maintain for each program. two is already enough. It's hard sometimes to add some new option to a program, and make sure the same is done to the man page.

[bl-ue]

I could write a Python script in 5 minutes to generate a markdown file from your hypothetical example. I could probably use unix tools, but I'm not proficient with them enough for that type of work.

[teuben]

I could write a Python script in 5 minutes to generate a markdown file from your hypothetical example. I could probably use unix tools, but I'm not proficient with them enough for that type of work.

probably me too. But I also discovered that man pages have some dialects. I will write one for our man dialect and see where it goes. the clock is now ticking.

[sbrl]

If you're planning on submitting said pages to the main tldr pages repo here, please open a PR with just 1 page to start with so we can review - 400 pages sounds like a lot of work for maintainers :-)

[teuben]

If you're planning on submitting said pages to the main tldr pages repo here, please open a PR with just 1 page to start with so we can review - 400 pages sounds like a lot of work for maintainers :-)

no, i would prefer we can use a client with a flag to refer to my tldr root. The idea is that my example can scale to other niche projects.

[teuben]

I could write a Python script in 5 minutes to generate a markdown file from your hypothetical example. I could probably use unix tools, but I'm not proficient with them enough for that type of work.

probably me too. But I also discovered that man pages have some dialects. I will write one for our man dialect and see where it goes. the clock is now ticking.

sad. 25 minutes.

[bl-ue]

Well, if you want to realistically estimate the time for a task, take your initial estimate and multiply it by 100. 500 minutes seems like about how long it would take for me irl 😁

[teuben]

The script is here: https://github.com/teuben/nemo/blob/master/src/scripts/man2tldr.py

[sbrl]

I see @teuben. Related issues: #2051, #3269, #4344

In short: That's a client specific feature

[teuben]

An alternative approach is using the man command itself, e.g.
man --pager='less -p ^TLDR' {{command}}

and @sbrl mentioned one issue where https://github.com/Phuker/multi-tldr was mentioned.

[EmilyGraceSeville7cf]

Smth like that is planned and will be implemented by myself.

[pixelcmtd]

@EmilySeville7cfg i already did it m8

[EmilyGraceSeville7cf]

Nice to hear. 😄