Include command line help output of fpm
awvwgk opened this issue · 6 comments
We should try to convert the output of fpm's command line help to markdown and include it in the reference section of the documentation.
Related:
- Cargo's command line help page: https://doc.rust-lang.org/cargo/commands/cargo.html
cc @urbanjost
I showed a couple of examples of doing this, as the original design of the help text was intended to be automatically converted to man-pages and HTML. I misplaced the best script, but it should be pretty easy to put it into a CI/CD script (I did it once as a demo, must be on another box but I am sure I kept it) that converted it to HTML. I tried going to markdown and I think the best result is in manual_2.md in the docs directory in https://github.com/urbanjost/fpm-tools/tree/main/docs so far. Assuming we can clean it up how does that look? The HTML that gets generated from the man-pages is not that great technically but I think looks better, but when I used pandoc to convert the HTML back to markdown it came out worse than just going straight to markdown from the manpages using pandoc, I think. The txt2man and man2html files are on the same site explicitly so they can be easily accessed from a build script, as they are modified from the originals. I had to tweek txt2man to do a better job with Fortran.
Once question is to whether to make a single document or to make a page for each topic and make an index. The index might be a little harder to automate, but it looks like pandoc might be able to do that automatically. Have not tried it. I think trying to automate it is worth it, as it is still changing frequently.
Looking at cargo it looks like it also releases the help as man-pages. That is definitely easy as that is exactly what it is designed for, so just run through the modified txt2man(1), if that is desirable.
@urbanjost @awvwgk I would like to document some changes i.e. fpm returning an application's exit code. I've done that in the FORD documentation (fortran-lang/fpm#858) but as @henilp105 @arteevraina suggested that's not straightforward to find. I was thinking to document the fpm CLI in a new Markdown page on fpm-docs but then I've stumbled upon this thread.
Where should I do that?
Looking at Cargo, it seems like they also manually maintain .md pages, which are then deployed to both a website and man pages.
So, would that be enough for now if I add .md pages to the current Sphynx site? As we have more Markdown pages, that could grow with time, to become a full documentation site like Cargo has.
Another option is to add to the current FORD documentation but I don't like it as much, it's harder to navigate and not as visually appealing.
It was originally designed so commands like txt2man, man2html, and pandoc could take the output from the fpm CLI and automatically generate man-pages, markdown, and HTML documentation. It could be done in a CD/CI script on github so that each version had it's own set of documents and/or be included in the distributions or as tar balls on the fpm-docs page as well.
Considering you have to follow certain simple rules for the flat text to convert to man-pages via txt2man it is somewhat surprising that there seems to be little or no changes required, as that was never formally adopted but it was designed to be automated and part of the PR process originally, at least in my imagination :> The fact it is not already automated seems to indicate some resistance to the idea but I have never seen it verbalized; but in a CD/CI script with fpm installed you just wget txt2man and you can do things like "fpm --help|txt2man >man/man1/fpm.1fpm" for each of the topics to generate the manpages; and then use one of the other tools to convert the man-pages to markdown, HTML, and so on. I use such at automated process for essentially all my own repositories so the documents are automatically extracted from the code and turned into man-pages and html, and a CLI interface that can be used as an fpm plugin that I like to use for libraries. Not sure everyone should go there but the part using prep(1) and making the input text files is the oddest part and not needed for fpm which already has help text, so it seems reasonable to me. Maybe instead of changing all various fpm install packages some separate man-page package that contained fpm and stdlib man-pages would be useful for Unix-like-systems; and the above methods could be used to post md/HTML to the fpm-docs pages.
Thank you @urbanjost for the explanation. So, the original idea was to extract documentation from the Fortran code into the man pages and possibly the documentation site. This is basically the opposite that Cargo seems to be doing, where the documentation site is built manually (not from the source code) even if the man pages are still built automatically from that.
I would personally lean towards using the same approach (Markdown pages -> man pages), because I think Markdown is free form and easier to collaborate upon here on GitHub, but maybe it would be nice to have other opinions on what's the best direction before taking any endeavor? @certik @awvwgk