Added a man page

[jolly-fellow]

A page for the man utility has been added. It includes a markdown file, a script for generation of a man page by pandoc utility and a generated man page.

[ScottBailey]

This is a useful script, but maybe we should build the manpage from cmake?

Here's a cmake module file that might help or we can work through it together. I imagine this is a custom target and an install command.

[jolly-fellow]

This is a useful script, but maybe we should build the manpage from cmake?

Here's a cmake module file that might help or we can work through it together. I imagine this is a custom target and an install command.

I don't know. I left this script just to save a command for conversion. Anyone can edit the markdown file and just run the script instead of reading pandoc documentation. Of course you may add building of the man page anywhere you wish. But when you do editing of the page you may convert it manually for many times in order to see how it looks on terminal. So IMHO building man pages during building of the project or the installation package is another task which doesn't take a content of the page.

[ScottBailey]

We should avoid adding build artifacts to our repo. Please remove. But do address Bucky's comments in the source file.

[ScottBailey]

Per Bucky's comments above, please convert aproj to antler-proj.

[ScottBailey]

Please remove the build artifact, change aproj to antler-proj, and update the CMake file to build the man page.

[jolly-fellow]

Please remove the build artifact, change aproj to antler-proj, and update the CMake file to build the man page.

If you mean that the antler-proj.1 file is a build artifact I'm not agree. It is a documentation and it doesn't make sense to consider it the same way as C++ source code. It has value itself. It may be printed as man ./antler-proj.1 right in the command line or opened in midnight commander which can render it too. It doesn't make sense to force a developer, who just cloned the repo, install pandoc and run CMake only to see a man page as a man page.

[ScottBailey]

antler-proj.1 is built from antler-proj.1.md using pandoc.

My concern is two fold:

1. a change to the source does not result in an automatic update to the artifact.
2. we lack an install target for the artifact.

Additionally, I believe the risk of the artifact losing sync to source is more problematic than needing to install pandoc to view a potentially out of date manpage... And the user can always open the .md source file anyway.

[jolly-fellow]

antler-proj.1 is built from antler-proj.1.md using pandoc.

My concern is two fold:

1. a change to the source does not result in an automatic update to the artifact.

2. we lack an install target for the artifact.

Additionally, I believe the risk of the artifact losing sync to source is more problematic than needing to install pandoc to view a potentially out of date manpage... And the user can always open the .md source file anyway.

IMHO building of code and writing of documentation are different tasks. So I propose to add the document and then talk about how to integrate it to the building process. IMHO it should include not only installation of pandoc and conversion but also building of the install packages. Maybe it make sense to think about conversion to help formats of other supported systems because Windows doesn't support man. Again it is a separated big issue but it is not a cause don't add a man page right now. Anyway if you believe it should be in CMake file add it as you wish, you know better how it should be I'm not against it. I just want to leave the man file in order don't force people install pandoc just to get the man page.

Could you tell a realistic scenario how somebody may change a man file directly and it will be approved and make a big problem? Anyway if you add the conversion step into the building process it will recreate the man file.

[jolly-fellow]

Created issue #25 to address missing build and install targets.

[ScottBailey]

Issue #25 addresses my outstanding comments.