Author Topic: Man Page  (Read 10993 times)

Offline kkmic

  • Commander
  • *****
  • Posts: 582
  • Undefined
    • View Profile
Man Page
« on: February 12, 2012, 11:18:38 pm »
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.

Offline SupSuper

  • Lazy Developer
  • Administrator
  • Commander
  • *****
  • Posts: 2162
    • View Profile
Re: Man Page
« Reply #1 on: February 13, 2012, 08:19:27 pm »
What exactly is a man page? ???

Offline kkmic

  • Commander
  • *****
  • Posts: 582
  • Undefined
    • View Profile
Re: Man Page
« Reply #2 on: February 13, 2012, 10:09:19 pm »
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 :D

Offline winterheart

  • Colonel
  • ****
  • Posts: 180
  • Fellow Squaddie
    • View Profile
Re: Man Page
« Reply #3 on: February 16, 2012, 12:52:08 pm »
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.

Offline kkmic

  • Commander
  • *****
  • Posts: 582
  • Undefined
    • View Profile
Re: Man Page
« Reply #4 on: February 16, 2012, 01:47:21 pm »
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 :P)

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

Offline winterheart

  • Colonel
  • ****
  • Posts: 180
  • Fellow Squaddie
    • View Profile
Re: Man Page
« Reply #5 on: February 17, 2012, 09:34:19 am »
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

Offline kkmic

  • Commander
  • *****
  • Posts: 582
  • Undefined
    • View Profile
Re: Man Page
« Reply #6 on: February 17, 2012, 10:48:20 am »
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

Offline winterheart

  • Colonel
  • ****
  • Posts: 180
  • Fellow Squaddie
    • View Profile
Re: Man Page
« Reply #7 on: February 17, 2012, 01:36:34 pm »
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.

Offline kkmic

  • Commander
  • *****
  • Posts: 582
  • Undefined
    • View Profile
Re: Man Page
« Reply #8 on: February 17, 2012, 04:12:00 pm »
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?

Offline winterheart

  • Colonel
  • ****
  • Posts: 180
  • Fellow Squaddie
    • View Profile
Re: Man Page
« Reply #9 on: February 17, 2012, 04:17:00 pm »
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.

Offline gchevallereau

  • Sergeant
  • **
  • Posts: 41
    • View Profile
Re: Man Page
« Reply #10 on: February 17, 2012, 09:44:20 pm »
Quote
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

Offline kkmic

  • Commander
  • *****
  • Posts: 582
  • Undefined
    • View Profile
Re: Man Page
« Reply #11 on: February 18, 2012, 09:51:54 am »
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
« Last Edit: February 18, 2012, 12:52:00 pm by kkmic »

Offline gchevallereau

  • Sergeant
  • **
  • Posts: 41
    • View Profile
Re: Man Page
« Reply #12 on: February 18, 2012, 12:41:15 pm »
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.