On 02/07/2012 09:33 AM, Fabio M. Di Nitto wrote: > On 02/07/2012 05:20 PM, Steven Dake wrote: >> On 02/07/2012 08:55 AM, Fabio M. Di Nitto wrote: >>> On 02/07/2012 02:07 PM, Jan Friesse wrote: >>>> Corosync has many manpages, but sadly many of them are out of sync with >>>> current codebase and some of them doesn't exists at all. >>>> >>>> Current priorities are: >>>> 1. man pages for every binary >>>> 2. man pages for every api >>>> 3. update docs to match code base >>>> 4. document error codes >>>> 5. Remove AIS references >>>> >>>> Volunteers are welcomed. Problem finder scripts are included. >>>> >>>> Complete results included bellow, for now, I can split work into few >>>> major parts: >>>> - CFG - need complete description, nothing done there >>>> - CPG - need document few functions + changes (default async mode, ...) >>>> - SAM - describe cmap flag (Honza) >>>> - *QUORUM* - describe few functions >>>> - CFG, CPG, *QUORUM*, EVS - error code descriptions >>>> - IPC - one page with common IPC errors description. At least overview >>>> has link to that page >>>> - AIS reference removal >>>> >>>> Current results: >>>> >>>> 1 - man pages for every binary >>>> ------------------------------ >>>> bash mp-check-bin.sh corosync-1.99.1-1.11.7d06.el6.x86_64.rpm >>>> >>>> @@ -4,0 +5 @@ >>>> +corosync.conf >>>> @@ -8,0 +10 @@ >>>> +corosync_overview >>>> @@ -10,0 +13 @@ >>>> +votequorum >>>> >>>> In other words, all binaries are documented and after brief look they >>>> looks ok and up to date. >>> >>> You probably want to differentiate .8 man pages from .5. votequorum >>> exists only in .5 specifically (there is no binary) and it is >>> effectively an extension to corosync.conf.5. >>> >>> >>>> No overview for quorum >>>> No description for quorum_trackstart >>>> No description for quorum_trackstop >>>> No errors documented in man/quorum_context_get.3 >>>> man/quorum_context_set.3 man/quorum_dispatch.3 man/quorum_fd_get.3 >>>> man/quorum_finalize.3 man/quorum_getquorate.3 man/quorum_initialize.3 >>>> No description for votequorum_trackstart >>>> No description for votequorum_trackstop >>>> No errors documented in man/votequorum_context_get.3 >>>> man/votequorum_context_set.3 man/votequorum_dispatch.3 >>>> man/votequorum_fd_get.3 man/votequorum_finalize.3 >>>> man/votequorum_getinfo.3 man/votequorum_initialize.3 >>>> man/votequorum_qdevice_getinfo.3 man/votequorum_qdevice_poll.3 >>>> man/votequorum_qdevice_register.3 man/votequorum_qdevice_unregister.3 >>>> man/votequorum_setexpected.3 man/votequorum_setvotes.3 >>> >>> quorum and votequorum library can really use the common IPC error >>> reference. There are no exception in the libraries to grant a specific >>> section. >>> >>> Fabio >>> >> >> While I realize a common error code man page would be less work, I find >> personally when I use man pages that I'd like all return codes the API >> can produce in the particular man page I am referencing. > > > I generally don't disagree, but at least let's make a common template > that we can include in all man pages. I see no benefit to maintain N > copies of the same piece of information. > > If nothing we can have (for example): > > foo_initialize.3.in ipc_errors.3.in > > some Makefile magic > > foo_initialize.3 > > all nice and updated a teach build. > > Fabio This makes sense, but I'm not quite sure how to do the makefile magic. :) Care to take on a template and then we can divide out the work for each man page to the appropriate owner? Regards -steve _______________________________________________ discuss mailing list discuss@xxxxxxxxxxxx http://lists.corosync.org/mailman/listinfo/discuss
