-
-
Notifications
You must be signed in to change notification settings - Fork 4.1k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
generating TLDR md files from a TLDR section in the man page #6154
Comments
Sounds like an interesting project! Are you planning on interfacing with the tldr-pages ecosystem in any way? |
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? |
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. |
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 ;-( |
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! |
(Holy cow, that repo is 34 years old!!! 🤪) |
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. |
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. |
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. |
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. |
sad. 25 minutes. |
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 😁 |
The script is here: https://github.com/teuben/nemo/blob/master/src/scripts/man2tldr.py |
An alternative approach is using the man command itself, e.g. and @sbrl mentioned one issue where https://github.com/Phuker/multi-tldr was mentioned. |
Smth like that is planned and will be implemented by myself. |
@EmilySeville7cfg i already did it m8 |
Nice to hear. 😄 |
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.
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
The text was updated successfully, but these errors were encountered: