Hi Brian, Thanks for the careful review. Attach please find the update man page.
On 08/20/09 05:46 AM, Brian Cameron wrote: > Alfred: > > ---noconfig ignore any configfile found. > > --v, --version Display the current version of > coherence. > > Why are some of the option description capitalized and others are not. > I'd think, for example, "ignore" should be "Ignore". > > I also think "configfile" should be "configuration file". > > --c, --configfile=file Specify the location of the configu- > ration file. The default location is > $HOME/.coherence. Example config > file can be found at /var/coher- > ence/coherence.conf > > You correctly use the <replaceable> tag as follows on the left-column: > > "--configfile=<replaceable>file</replaceable>" > > However, in the description you should also use the same tags whenever > you use the same word. For example, the description should say: > > Specify the location of the configuration > <replaceable>file</replaceable>. The default locaiton is > $HOME/.coherence. An example configuration > <replaceable>file</replaceable> can be found at /foo." > > Note also change "Example config" to "An example configuration". > > the option isn't specified. > > Man pages should not use contractions like "isn't" or "don't". Use > "is not" or "do not", etc. > Updated. >>> > ence provides an implementation of: a SSDP (Simple Service >>> > Discovery Protocol) server, a MSEARCH (command to find other >>> > devices connected to the UPnP network) client to find other >>> > devices connected to the network, server and client for >>> > HTTP/SOAP requests, server and client for Event Subscription >>> > and Notification. >>> >>> This might look better as an<itemizedlist>. Refer to the pkg-config.1 >>> manpage and see how it uses the<itemizedlist> and<listitem> tags. >>> >>> >> Updated. >> > Looks better to me. What do you think? > Yes, it looks much better. >>> > For users, Coherence can be used in conjunction with >>> > Rhythmbox, Totem or Elisa, and become a controllable >>> >>> When you refer to programs like elisa, rhythmbox, totem, etc. you >>> should refer to them with<citerefentry> tags so they look like this: >>> >>> For users, Coherence can be used in conjuction with rhythmbox(1), >>> totem(1), or elisa(1); and become a controllable. >>> >>> Note a semicolon is a bit better grammer before the word "and". >>> >>> >> Updated. >> > box(1), totem(1), elisa(1); and become a controllable > > You forgot the word or - "or elisa(1)" > > Just to explain, when a sentence includes a list of items and you > also need to use a comma to break the sentence, then you use a semicolon > to break the sentence. For example > > I don't like to eat fish, cheese, and milk; but I do like to eat. > > You could also avoid the use of the semicolon by breaking it into > two sentences. > > For users, Coherence can be used in conjunction with rhythmbox(1), > totem(1), or elisa(1). When used in this way, these programs become > a controllable..." > > This is actually a little less awkward than using a semicolon, I think. > Updated. Thanks for the explanation. >>> > Example: -- >>> > plugin=backend:FSStore,name:MyCoherence >>> >>> I would add an EXAMPLES section and move this example to that section. >>> Would be nice to provide some other examples since it sounds like >>> coherence can be configured to run a lot of different ways. >>> > Why no EXAMPLES section? Manpages should have an EXAMPLES section if > you want to follow the Sun manpage style guide. Not all of our manpages > do, though. > Added EXAMPLES section. >>> > --p, --plugin=plugin activate plugin >>> > Available backends are: >>> >>> In the first line you refer to it as a "plugin" but in the next line you >>> refer to it as a "backend". We should use the same term. What is the >>> default value? >>> >>> >> Please note that one plugin contains several keyword: backend/plugin >> name. I think the use of "backend" here doesn't conflict with "plugin". >> Users can activate certain plugin by specifying key "backend" to one of >> the available backends, FSStore for example. >> > It might be nicer to explain this in the manpage, and not just to me. > :) > Added to the man page. >> I don't think it's good to provide examples as almost all the available >> backends involve trademark issue. And the above one-liner is the generic >> example. Users can replace the backend/plugin name with the one they like. >> > It would still be good to move the example to an EXAMPLES section. You > really should not provide an example inside the description of an > option. > > Is it really impossible to give any other examples of how to use > coherence without mentioning a trademark? Some of the options seem > to not be trademarks (e.g. ElisaPlayer). > Added. Best Regards, -Alfred >>> > SEE ALSO >>> > python(1), attributes(5) >>> >>> You refer to programs like totem, elisa, etc. in the manpage. Any >>> program you refer to in the manpage should be mentioned in the "SEE >>> ALSO" section. >>> > Looks good. As with any manpage, you can always make them better. :) > I do not think any of the issues that I mention above are critical to > fix, but you might want to fix the easier ones. > > Brian > -------------- next part -------------- An embedded and charset-unspecified text was scrubbed... Name: coherencev3.txt URL: <http://mail.opensolaris.org/pipermail/jds-review/attachments/20090821/e649e18c/attachment.txt> -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://mail.opensolaris.org/pipermail/jds-review/attachments/20090821/e649e18c/attachment.html>
