elixir-lang
Output man pages
When OTP switched to using ex_doc in OTP 27, we lost the man pages for the OTP modules.
Would you accept a PR to produce man pages, or is there a way to access the intermediate markdown format and use an external tool (e.g. pandoc) to generate man pages from it?
Example of an OTP man page from OTP 26:
It probably makes the most sense for us to have a markdown output. Then you can use something like pandoc to convert it to man. :) PRs exploring this would be welcome!
I remember some years ago I proposed having a Markdown formatter. I think having the documentation in this format opens up the possibility to a lot of things.
Now that I have some free time I can look into working on an implementation. What would the basic requirements be?
I can't think of many requirements, actually. I guess the only question is if it is one markdown file per module or one per function. If it is one per module, then it is equivalent to our other formatters, but probably considerably simpler.
One per module matches the old OTP man pages, so for this use case, it's perfect.
I would go with one file per module per file. This way the documentation could be readable over a terminal with less or markdown reader.
We have an escript that converts a subset of markdown to man pages: https://github.com/erlang/otp/blob/master/make/markdown_to_man.escript. So if ex_doc could generate markdown documents for each module, that escript could be used to create man pages for it.
Note that the escript is on intended for general use, only of the subset of markdown used by the Erlang/OTP docs.
I'm already working on it, and I have a draft working version. I will create soon an issue so we can discuss about anything related to this feature.
Here's the PR https://github.com/elixir-lang/ex_doc/pull/1992 with the Markdown implementation.
You can see the generated markdown files in this repo https://github.com/eksperimental/ex_doc_markdown_formatter_docs and tell me if that would suit your needs for generating the man pages or if there is something that needs to be changed/added.
Erlang is adding their own man page handling on top of Markdown, which probably makes more sense since they can handle it directly from the terminal without generating the man pages upfront.
If someone wants to do a man pages version for ExDoc, we will gladly accept it once the Markdown work is done. Thanks!
Erlang is adding their own man page handling on top of Markdown, which probably makes more sense since they can handle it directly from the terminal without generating the man pages upfront.
You mean they will extract the doc attributes directly from the Erlang parse trees, without using ex_doc?
ExDoc never extracted the parse trees, we assume something else does and puts it in the .beam. So they are writing something that reads the markdown from .beam and converts it to man :)