On 02/07/2012 06:05 PM, Steven Dake wrote: > 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? Ok, I'll make the build magic and change one man page to reference the template, but somebody will have to write the full IPC man page bit. Then converting all common man pages should be a batch job. Fabio _______________________________________________ discuss mailing list discuss@xxxxxxxxxxxx http://lists.corosync.org/mailman/listinfo/discuss
