openfortivpn
openfortivpn copied to clipboard
adrienverge
HTML or wiki (Markdown) version of the man page?
An online readable version of the man page might be nice.Easier to read and find for web users. Either plain HTML or Markdown that can be integrated in the project wiki. I don't know how much this could automated.Where to host it? What format to use?
I've tried man-to-md and the result is terrible. Perhaps it can work with substantial modifications to the man page - or perhaps it's hopeless at this point, I really don't know.
I see this as more maintaining work, so if it would be only my choice I would just emphasize on "use man openfortivpn to see all options". But I agree it would be nice for new users, not accustomed to man.
I don't think raw HTML is the most suited, as it's harder to read and write, and brings lots of unneeded options. Markdown could be a good option. On other projects I usually use RST, which gives a bit more flexibility than Markdown, doesn't have its flaws (like the impossibility to use ` inside ``), and is simple too.
groff -mandoc -Thtml converts to HTML much better.
I too prefer Markdown but haven't found how to convert yet.
Perhaps pandoc is a better choice. But I agree it's too much work and maintenance.
The openfortivpn.org domain could be a hosting place. I can set up a cronjob that does the update. I'd have to upgrade the hosting package, but if there is a real benefit I'm happy to do so.
If pandoc -o doc/openfortivpn.1.md doc/openfortivpn.1 produces an acceptable result for you, then a github action could generate the markdown and push it to the wiki. I could work on this, if you are interested.
I tried the above pandoc command and the result does have some issues. Do you think they can be fixed with pandoc options or changes to the man page?
The first issue can be easily fixed by adding --to gfm to the options (gfm being Github flavored markdown).
The second issue seems to be the direct switch from bold typeface to italics. We could fix it in the manpage by replacing \fB\-c \fI with \fB\-c\fR \fI. But actually, I think this might be an issue in pandoc. I'll dive in some more and report back.
TLDR: I think there is an issue with pandoc but we can easily workaround it until it is fixed. This command pandoc --to gfm openfortivpn.1 | sed 's/ \*\*\*/** */g' > openfortivpn.1.md gives me this result which looks decent to me. Shall I build this into a Github action?
Explanation: pandoc converts this \fB\-c \fI... into **-c ***... and the space after 'c' is not allowed in markdown when closing bold typeface. The space must be outside boldface, so **-c** *.... This is what the sed command does. I don't know if this is a bug in the manpage-reader or markdown-writer. Also, it might take a while until this is fixed, so I hope the sed command is okay.
There are other issues as well. No need to have something perfect from scratch, but we will have to address these and other issues.
Okay, that sounds like I could continue. Good news is that the next version of pandoc will have the other issue fixed: https://github.com/jgm/pandoc/issues/9445