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.
>> > 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?
>> > 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.
>> > 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.
>> > --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.
:)
> 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).
>> > 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
