Man Page

[kkmic]

I've slapped together a first draft for a Linux man page: https://bitbucket.org/killermosi/openxcom-man-page/

It is basically a copy/paste from the readme.

Until it will be added to the main trunk, please post your comments/additions/patches here.

[SupSuper]

What exactly is a man page?

[kkmic]

Now that's a question that left me a bit surprised.

https://en.wikipedia.org/wiki/Man_page

Basically, a man page is a quick/detailed help for a specific command/application. Not all applications have a man page, though most of them do. It is used in Unix and Unix-like operating systems.

You can try man command in any terminal.

man cp
man mv

and in the future, man openxcom

[winterheart]

Pure groff-format is hard to understand and maintain. What about Docbook XML? It can be easly converted with "xmlto" package to various formats including HTML and man.

[kkmic]

Pure groff-format is hard to understand and maintain.

Yeah, I've noticed that when I have attempted to edit a man page. I have actually started with another page and modified it until it reached the current form

I'll take a look at Docbook XML, as the name went by when I searched for tips and tricks for man pages. Any pointers? (I mean links )

If you're interested, I can give you access to the repo.

[winterheart]

Here example of openxcom xml docbook. You'll need xmlto and docbook-xml-dtd 4.5 packages.
To compile it to man-page, you just run
xmlto man openxcom.6.xml

[kkmic]

Looks good and it's way more human-readable than groff.

Question is: in what format should the openxcom man page be included in the source? I'd personally vote for the groff format, as having it in Docbook format may add another package to the requirements list. Also, converting the man page from Docbook to groff is a 5 second job... an I don't see the man page changing too often

[winterheart]

In git should exist groff and xml. But, of course end user need only groff file. Just keep it up-to-date after each change made in xml-file.

[kkmic]

Yeah, my thoughts exactly.

Though I'm not afraid of getting my hands dirty with pure XML code, are you aware of any free Docbook editors?

[winterheart]

You can try XMLmind XML Editor (https://www.xmlmind.com/xmleditor/download.shtml). It can runs in Java enviroment, Docbook aware and Personal Edition is free.

[gchevallereau]

In git should exist groff and xml. But, of course end user need only groff file. Just keep it up-to-date after each change made in xml-file.

I disagree. There should be only the XML file:

• it's really easy to check for the presence of xmlto in both CMake and autotools.
• if there are both version, you can be sure that one day:
• someone will edit the generated file.
• someone will forgot to update the generated file after making a modification

[kkmic]

What I am looking for is to avoid one more required dependency for OpenCom.

How common are the two packages mentioned by winterheart?

My distro, for example, lacks xmlto by default.

Correction, xmlto is present in my distro by default

[gchevallereau]

as i have said, it's not hard to make the build of the man page optional, so xmlto wouldn't be a required dependency.
IMHO, we should treat it like doxygen. You can perfectly build openxcom without doxygen installed, because we check for it's presence and only add needed rules to generate documentation if it was found. man page should be handled the same way.