Skip to content
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

[FEAT] More documentation in the Manpage #830

Open
ValdezFOmar opened this issue May 1, 2024 · 7 comments
Open

[FEAT] More documentation in the Manpage #830

ValdezFOmar opened this issue May 1, 2024 · 7 comments
Labels
enhancement New feature or request help wanted

Comments

@ValdezFOmar
Copy link

ValdezFOmar commented May 1, 2024

Wanted features:

  • Include all the available options, currently only a subset (compared to fastfetch --help) is actually listed.
  • Include the information from running fastfetch -h <option> for all options.
  • Explain/give examples of the structure of the config file, accepted values for options, how to change common things, etc.
  • Include the JSON Schema found in the github wiki.

Motivation:

When I want to read thorough documentation for a tool I look at the manpage (as many others might do). I expect to find more information in man foo than running foo --help. Right now, some of the info is available in the manpage, more is in fastfetch --help and other is in the github wiki.

Having all the documentation in the manpage would be beneficial because:

  1. There would be a centralized place to look for the documentation, without needing to look at external resources or having to run multiple commands (running fastfetch -h <option> constantly is not very ergonomic).
  2. Users can leverage the features of the program they use to read manpages to search for specific topics of their interest more easily.
@ValdezFOmar ValdezFOmar added the enhancement New feature or request label May 1, 2024
@CarterLi
Copy link
Member

CarterLi commented May 1, 2024

The man page file was contributed by community, but I'm not familiar the man page file syntax.

Any contribution is welcome.

@ValdezFOmar
Copy link
Author

Neofetch used help2man to generate a manpage using output from --help. Another option is to use pandoc to convert from any format (eg. markdown) to a manpage.

I think that pandoc would be best because then you can convert the JSON schema to a manpage too.

@mac2net
Copy link

mac2net commented Sep 24, 2024

Any documentation is better than none and is the Man page really the best place to document what really should end up in the config.jsonc file? As such, I suggest just keeping the current release version and the JSON Schema pages in sync. Right now the latest version of Fastfetch is v25, released 5 days ago while the JSON Schema document was last edited two weeks ago, Cheers Mac

@darwincereska
Copy link

I fixed the man page I will send a pull request

@CarterLi
Copy link
Member

To someone wants to fix this

  1. We don't need the generated .1 file. We need a (python?) script to generate it, in order to regenerate it in future release.
  2. It should be generated directly from https://github.com/fastfetch-cli/fastfetch/blob/dev/src/data/help.json, not fastfetch --help

@ValdezFOmar
Copy link
Author

I'll see if I can have a go at it this weekend or next week. I've studied a bit of the format used for manpages (roff) to be familiar with it and I've seen other projects generate their manpage using a python script as you mentioned (also thanks for mentioning that help.json file, that really makes things easier).

@darwincereska
Copy link

I see that my pull request was outdated and not in the way that was requested, I will take a try at making a script to fix this issue

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
enhancement New feature or request help wanted
Projects
None yet
Development

Successfully merging a pull request may close this issue.

4 participants