[Cluster-devel] cluster3 man pages

[Cluster-devel] cluster3 man pages

[David Teigland]

In the process of updating content in my cluster3 man pages, I also tried
to align the style/structure/etc with this stanard:

http://www.kernel.org/doc/man-pages/online/pages/man7/man-pages.7.html

I think it would be nice to try to sync up all our man pages with those
conventions, it's been somewhat ad hoc in the past.  The following which
I've updated should be mostly in line with the standard, so you can copy
bits from them:

cluster.conf
dlm_tool
dlm_controld
gfs_control
gfs_controld
group_tool
groupd
fence_node
fence_tool
fenced
fence_ack_manual

One other advantage of doing this is that we should be able to use the
same tools to build online versions of the man pages as is done for the
man-pages project,
http://www.kernel.org/doc/man-pages/online/dir_all_by_section.html

[Cluster-devel] cluster3 man pages

[Fabio M. Di Nitto]

On 1/21/2010 5:28 PM, David Teigland wrote:
> In the process of updating content in my cluster3 man pages, I also tried
> to align the style/structure/etc with this stanard:
> 
> http://www.kernel.org/doc/man-pages/online/pages/man7/man-pages.7.html
> 
> I think it would be nice to try to sync up all our man pages with those
> conventions, it's been somewhat ad hoc in the past.  The following which
> I've updated should be mostly in line with the standard, so you can copy
> bits from them:

would it be possible to have a list of man pages that needs updating
instead? I am not man page expert, nor I have a gigantic interest to
learn the whole standard behind it but I can fix mine if I know they are
broken and what?s broken.

Fabio

[Cluster-devel] cluster3 man pages

[David Teigland]

On Thu, Jan 21, 2010 at 05:52:14PM +0100, Fabio M. Di Nitto wrote:
> On 1/21/2010 5:28 PM, David Teigland wrote:
> > In the process of updating content in my cluster3 man pages, I also tried
> > to align the style/structure/etc with this stanard:
> > 
> > http://www.kernel.org/doc/man-pages/online/pages/man7/man-pages.7.html
> > 
> > I think it would be nice to try to sync up all our man pages with those
> > conventions, it's been somewhat ad hoc in the past.  The following which
> > I've updated should be mostly in line with the standard, so you can copy
> > bits from them:
> 
> would it be possible to have a list of man pages that needs updating
> instead? I am not man page expert, nor I have a gigantic interest to
> learn the whole standard behind it but I can fix mine if I know they are
> broken and what?s broken.

The main issue is getting the content up to date, of course; many seem to
be out of date to one degree or another.  Standardizing the
structure/style at the same time is just a suggestion.

I also forgot to mention that it would be good to update cluster.rng
descriptions at the same time.  We want cluster.rng descriptions to be
only 1-2 line fragments, followed by a man page reference where more
details can be found.  (This is so the docs people can generate a
cluster.conf reference table.)

These are the man pages I haven't looked at, so I can't say what state
they're in,

ls -1 cman/man/
Makefile
cman.5
cman_tool.8
cmannotifyd.8
mkqdisk.8
qdisk.5
qdiskd.8

ls -1 config/tools/man/
Makefile
ccs_config_dump.8
ccs_config_validate.8
ccs_tool.8
confdb2ldif.8

ls -1 rgmanager/man/
Makefile
clubufflush.8
clufindhostname.8
clulog.8
clurgmgrd.8
clurmtabd.8
clustat.8
clusvcadm.8

ls -1 gfs2/man/
Makefile
fsck.gfs2.8
gfs2.8
gfs2_convert.8
gfs2_edit.8
gfs2_grow.8
gfs2_jadd.8
gfs2_quota.8
gfs2_tool.8
mkfs.gfs2.8
mount.gfs2.8

[Cluster-devel] cluster3 man pages

[Fabio M. Di Nitto]

On 1/21/2010 6:35 PM, David Teigland wrote:
> On Thu, Jan 21, 2010 at 05:52:14PM +0100, Fabio M. Di Nitto wrote:
>> On 1/21/2010 5:28 PM, David Teigland wrote:
>>> In the process of updating content in my cluster3 man pages, I also tried
>>> to align the style/structure/etc with this stanard:
>>>
>>> http://www.kernel.org/doc/man-pages/online/pages/man7/man-pages.7.html
>>>
>>> I think it would be nice to try to sync up all our man pages with those
>>> conventions, it's been somewhat ad hoc in the past.  The following which
>>> I've updated should be mostly in line with the standard, so you can copy
>>> bits from them:
>>
>> would it be possible to have a list of man pages that needs updating
>> instead? I am not man page expert, nor I have a gigantic interest to
>> learn the whole standard behind it but I can fix mine if I know they are
>> broken and what?s broken.
> 
> The main issue is getting the content up to date, of course; many seem to
> be out of date to one degree or another.

Absolutely agreed.

>  Standardizing the
> structure/style at the same time is just a suggestion.
>

Of course, I like the idea to be able to generate html man pages (maybe
even at build time). If you can help us spotting the format changes that
need to be done, that would speed up greatly.

> I also forgot to mention that it would be good to update cluster.rng
> descriptions at the same time.  We want cluster.rng descriptions to be
> only 1-2 line fragments, followed by a man page reference where more
> details can be found.  (This is so the docs people can generate a
> cluster.conf reference table.)

Indeed.

You made a lot of commits there, should be easy to follow your as example.

Fabio