Alfred:
> Thanks for the review. Attached is the updated man page for Songbird.
Looks really good. Some minor comments:
This manpage should include an OPERANDS section to describe the
[URL] operand described in the SYNOPSIS
songbird [options ... ] [URL]
Note operands should not be in all-caps. It should be "url" and
not "URL".
> uniquely open approach to Internet digital media network
I don't think Internet should be capitalized. Should just be
"internet".
> a wide range of audio formats(including mp3, AAC and ogg).
Should have a space before the leading parens (the '(' character).
I would not list mp3 or AAC in the manpage since these are not
supported on Solaris in GStreamer by default. Instead might be
better to just say "including raw audio, FLAC, Speex and ogg-vorbis"
> gstreamer plugins to support some formats.
Should be "GStreamer" and not "gstreamer". I'd say "media formats"
instead of just "formats".
> Songbird's add-ons system can be used to dynamically
> personalize the media player.
I think that should be "add-on system". Might be good to
explain how you can dynamically personalize the player.
> The Songbird Webpage API enables the ability to embed player
"enables the ability to embed" is a little wordy. Would be good
to more simply say "enables you to embed player"
> functionality into the web site so it can interact with the
I'd say "into a web site"
The SEE ALSO section should refer to gst-std-options(5) and
attributes(5)
Brian
> Brian Cameron wrote:
>>
>> Alfred:
>>
>>> Here comes the manpage for Songbird.
>>>
>>> songbird.1 is in sgml format. songbird.1.txt is the plain text
>>> version of the manpage for review. Most of the content comes from
>>> "songbird -h".
>>
>> songbird - The desktop media player mashed-up with the Web.
>>
>> I would just say "Desktop media player mashed-up with the web".
>> Starting the sentence with "The" makes it sound like the only media
>> player with these features.
>>
>> Songbird is a complete desktop media player or "jukebox"
>> with a uniquely open approach to Internet digital media net-
>> work services.
>>
>> Does it support CD playback? If not, then it probably isn't a
>> "complete" player. Might be better to be a bit more clear about
>> what features it has. The DESCRIPTION doesn't really tell me what
>> this program does aside from being a media jukebox.
>>
>> It seems that the arguments refer to profiles. Might be nice if
>> the DESCRIPTION defined what a profile does or means.
> Update the DESCRIPTION section to include the necessary information.
>> It isn't really clear to me what the "-no-remote" option does.
> As Songbird is a Mozilla-based application, most of its options come
> from Mozilla and similar with Firefox's options.
>
> If user wants to create a new process(Firefox for example) instead of an
> instance of the existing one, the option "--no-remote" is helpful. I
> tried this option with Songbird, it doesn't work. It's reasonable to me
> that there is only one Songbird process on one system for playing media.
> So I remove this part from the man page.
>>
>> -UILocale locale Start with the UI Locale listed:
>> locale.
>>
>> -contentLocale locale Start with the content Locale
>> listed: locale.
>>
>> I would say "Will use the specified locale with the UI" or "Will
>> use the specified locale with the content".
> Would it be good to highlight that Songbird will *start* with the
> UILocale and contentLocales user specifies?
>> -height value Set the height of startup window to
>> value.
>>
>> I would say "Specify the height value of the startup window". I
>> think that is just a bit more clear.
> I think it's more clear when the user views the real man page. There are
> underlines for "value", "locale" to highlight that these are
> user-defined value. The output of "man firefox" could be an example.
>> Since Songbird uses GStreamer, I'd think that referring to the fact that
>> it uses GStreamer in the DESCRIPTION would be nice.
> Updated.
>> I'd also include
>> gst-std-options(5) in the SEE ALSO section since I assume it supports
>> the standard GStreamer library options documented here. No?
> Most of Songbird's options come from Mozilla options, it doesn't have
> the GStreamer library options.
>
> Best Regards,
> -Alfred
