Alfred: > Thanks for the careful review. Attach please find the update man page.
Looks very professional, and does a good job of meeting the manpage style guide. Great work. Brian > 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 >> >
