Investigate the possibility of converting the README files to man pages using @sunaku's md2man.
The files will look similar to bellow, inspired by Zsh and Git man pages.
Where will these man pages be stored?
If the README files can be successfully converted as they are or altered, should they be removed in favour of man pages only?
README files should be kept, with manpages being auto-generated from them. Troff is harder to read and edit than Markdown, and Github doesn't render troff nicely. Users would basically loose the ability to read Prezto documentation on Github.
It seems that @sunaku's md2man doesn't like image tags used in screenshots.
I have been toying with this in the issue/276 branch. Feedback, ideas, testing is welcome.
The README files will have to be modified to look more like man pages. There are examples in the md2man repository.
@ColinHebert What do you think of this?
I am not against man pages for prezto, but I wonder if it's really useful/necessary.
If we consider that it is, I think we should keep the markdown version in git and let the user build the man itself.
Maybe a module "man" with a simple script going through every available module and generating the appropriate manpage for each of them (based on their readme.md and named after the folder name).
This module cold have options such as "folder used to store the manpages", and if no folder is specified, automatically use $PREZTO_HOME/Doc (which will be ignored in git) and add it to the manpath.
Or an "automatically generate the documentation" option so the user doesn't even have to worry about generating it, and a "documentation generation frequency" defaulting on "once".
It should be possible to run the script manually (if needed).
As I said I don't know if it's necessary, maybe it could be in a module, but one thing is sure, the current documentation should stay as it is.
Mostly because it's a logic placement for the documentation in github: that is really nice to read and discover the code.
The generated documentation should not be stored in git, because (as a rule of thumb) generated content shouldn't be under version control.
Yes, and I'm not really convinced that having all the documentation in one folder is the best way to go in the prezto case.
Regarding the man pages, as I said, I don't think we should keep them in the repository, but let the user generate them when/if needed
The problem is that generating them requires three gems, and as you may know, assuming that Ruby is available, installing gems is a PITA.
I think the document files are too scattered (each model has an independent document in each model folder, and we should go to different folders to find documentary file for different models). Could you generate a good organized documents? For example. using Sphinx (it is very popular among python society).
You can have organized documents with md2man-html(1) output just as well. 💡 Look at my Tork project's HTML man pages for example! Also, note that UNIX manual pages traditionally link to each other by name; this is readily apparent in "SEE ALSO" sections found at their ends.
Remove old doc directory