Add a `hoa help` command (man pages powered)

[CircleCode]

hoa help and derivates like hoa help command would be really useful to document commands and their options, like for example pragmas ( hoaproject/Compiler#52 ) for Compiler.

hoa help would then use man if available, and fallback to other format.

[Hywan]

Who would like to lead this work? We need to define the tasks precisely. First draft:

• [ ] Man pages will be located in <library>/Documentation/Man/,
• [ ] The 3 and 5 Sections 1 will mainly be used, respectively Library Functions Manual and File Formats Manual (so <library>/Documentation/Man/3/Foo and <library>/Documentation/Man/5/Foo, or <library>/Documentation/Man/Foo.3 and <library>/Documentation/Man/Foo.5),
• [ ] They must be integrated to the hack books,
• [ ] They will be accessed by hoa help <command> or hoa <command> --help.

This list of proposals does not question the “How”, only the “What”. If agree, then we should open one issue per proposal.

Thoughts?

[Hywan]

Note: I felt in love with rustc --explain and I have always been dreaming about a hoa help --explain. To explain what? Exception codes for instance, this is an excellent start!

[Jir4]

:+1: for this features. Seems to be a huge work , maybe we have to split it.

[Hywan]

Not that huge. Let's focus on a small library to implement this. To avoid having cross-library PR, we can implement this on Hoa\Cli, so that hoa help cli:help would work (or hoa help help, like man man). Else, when it will work, we will have to open issue on all libraries to write the documentations. It's like writing hack books ;-).

[shulard]

:+1: for the feature !

[1e1]

+1 It looks like the Linux man (as the Data tree). What about lazy developers who like write a single sentence embed in the code. Yes, it's really not a best practice but usual. Cf nice frameworks as Symfony ;) How many PHP developers are still using Windows or ignoring Linux concepts. I think it could be interesting to write MarkDown manuals. Even if Hoa needs to translate it into "man" format.

Remember that PHP is cross-platform. But keep in mind that Data is like a Linux tree and serious developers use Linux ;)

[Hywan]

What about lazy developers who like write a single sentence embed in the code. Yes, it's really not a best practice but usual.

What?

Markdown is nice to write but horrible to parse. If we provide man pages, this is easy to print or transform for Windows, while Markdown will need to be compatible everytime. Not CPU friendly :-).

[Hywan]

How to write a man page. Based on the Troff language, looks horrible :-/.

[Hywan]

I was reading cURL source code when I saw this: http://daniel.haxx.se/projects/roffit/. It helps to compile Roff to HTML, which might be useful.

[Hywan]

See cURL man pages, https://github.com/curl/curl/tree/master/docs/libcurl. It's not that horrible after all. Just strange when you're used to read XML or TeX, but that can be fine :-).

[CircleCode]

why not using xyl? this way, doc pages could be converted into man either statically or dynamically, and the windows output could be generated on the fly

[Hywan]

@CircleCode Yup. I am just afraid to require hoa/xyl, and so a big part of Hoa, just for man pages :-/. But it sounds logic.

[1e1]

Yep! +1 for xyl. But I would highlight Symfony developers can write a description of a CLI action inside the code. It's not a manual, but it's the main practice I saw (not the best, I mean)

[1e1]

@Hywan The man could be read in the Terminal. But it could be publish. And I like the "code once, FILL everywhere" ;)

[shulard]

Perso je serais aussi :+1: sur l'utilisation de Xyl, pourquoi utiliser un nouveau langage quand il y en a déjà un qui est utilisé :smile:.

[Hywan]

@1e1 If you do this: https://github.com/hoaproject/Cli/blob/47c65a0aecc77bc8a6a0db959efadd39ed73271d/Bin/Welcome.php#L238, then the line will be used as a description in the hoa welcome command (to list all available commands).

@shulard @CircleCode Isn't it annoying to grab hoa/xyl with all its dependencies just to print a man page? You can easily write a new interpreter in XYL to support Roff, that's easy. Just a little bit time consuming, but a nice exercice for those who you would like to discover XYL.

[1e1]

Who wants export its library could built it. It's man pages will be a "dot man" in a phar. While its source is a "dot xyl"

(@Hywan relative to the welcome CLI, I don't know where I can notice "\n" should be replaced by "PHP_EOL". A thought for Windows users ;) )

[Hywan]

@1e1 About PHP_EOL, open an issue if you think this is important.