Hi Brian, Thanks for the review. Attached is the update man page for Coherence. Please see my comments below:
On 08/18/09 03:35 PM, Brian Cameron wrote: > Alfred: > >> Here is the man page of Coherence for review. >> > Looks really good. Some comments: > > > written in Python for the Digital Living. > > Not sure what the above means. Is "Python for the Digital Living" > a language that coherence is written in? > Updated to remove "for the Digital Living". > > 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. > > The virtual devices contain: Media Server to provide media > > content (local storage or online services) and directory > > information, Media Renderer to play back media content pro- > > vided by the Media Server, Control Point to interconnect > > Media Server and Media Renderer. > > Also might look better as an <itemizedlist>. > Updated. > > 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. > > For example, Coherence is used in > > Elisa to talk with the Apple Movie trailer Media Server for > > its Movie trailer plugin and YouTube Media Server for its > > YouTube plugin. > > "Apple" and "YouTube" are trademarked, and you would need to work with > SunLegal to properly refer to these trademarks if you really want to > include this text. I'd either remove the example, or provide a more > generic example that avoids referring to trademarks. > Removed to avoid trademark issue. > > ---noconfig ignore any configfile found > > --c, --configfile=file configfile [default: > > $HOME/.coherence] > > I would say something like "Specify the location of the configuration > file" rather than just saying "configfile" as the description. > Normally we don't use syntax like [default: $HOME/.coherence]". > Instead I would say "Specify the location of the configuration file. > The default location is $HOME/.coherence." > Updated. > The manpage provides no information about what the configuration file > should or can contain. Should it? > Put a reference to /var/log/coherence.conf. > > --l, --logfile=file log file > > I would say something like "Specify the location of the log file." > What is the default value? If there is no log file if the argument > is not specified you should say so. > There won't be log file if the option isn't specified. Updated. > > 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. > > > --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. 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. > > FILES > > ~/.coherence Per user configuration file. > > What about the default log file location? Or is there no logfile if > none is specified on the command line? > As mentioned above, no log file will be used if the option isn't specified. > > 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. > Updated. Best Regards, -Alfred -------------- next part -------------- An embedded and charset-unspecified text was scrubbed... Name: coherencev2.txt URL: <http://mail.opensolaris.org/pipermail/jds-review/attachments/20090819/c1bdcf30/attachment.txt> -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://mail.opensolaris.org/pipermail/jds-review/attachments/20090819/c1bdcf30/attachment.html>
