Jerry:
Overall it looks much better.
This description is an improvement on what was before.
libgpilotd, libgpilotdcm, libgpilotdconduit are three core
gnome-pilot libraries. libgpilotd is for gnome-pilot daemon.
libgpilotdcm is for gnome-pilot conduit management. libgpi-
lotdconduit is for gnome-pilot conduits.
However, I don't think this really does a good job communicating
to the end user which ones they would want to use, or for what
purpose(s). You say "libgpilotd is for the daemon", but don't explain
why or when an end user would want to use this. Would I care about
libgpilotd if I wanted to write my own daemon, or would I use it
for other purposes? Is this really a private library that the
daemon uses but end users wouldn't ever need to use? Just not very
clear to me.
Likewise, it what situations would I want to make use of the conduits
interfaces? There seems to be two conduit libraries, how would I make
use of them if I were writing my own conduit?
While manpages don't necessarily need to go into full detail, they
should (at least) explain to the end user why they care about these
libraries, or when they should consider using them.
Brian
> Brian Cameron wrote:
>>
>> Jerry:
>>
>>> libgpilotd:
>>>
>>> - The DESCRIPTION should probably mention a little bit about the 3
>>> individual libraries described in this page. What is the purpose of
>>> each one?
> I added a paragraph to describe their purposes into the manpage.
>>
>> I fixed all the below issues already for you
> Thanks a lot for your kind help.
>> , but you should still
>> consider addressing the above issue.
>>
>> One question, though. Some of the pilot manpages refer to
>> pilot-xfer(1), but there does not yet seem to be a manpage for this
>> program yet.
> We have shipped the manpage for pilot-xfer. If you do "man pilot-xfer",
> you will see it.
>> Either we should add this pilot-xfer manpage and make
>> sure all the SEE_ALSO sections of the existing pilot manpage refer
>> to it, or we should remove the SEE_ALSO references if we don't plan
>> on delivering this last manpage.
>>
>> Brian
>>
>>
>>> - Shouldn't pilot-xfer(1),gpilot-install-file(1) both be mentioned in
>>> the SEE ALSO section?
>>> - You shouldn't mention gpilotd(1) in the "SEE ALSO" section of the
>>> gpilotd(1) manpage.
>>> - pilot-xfer(1) should be listed in alphabetical order in the "SEE ALSO"
>>> section. Therefore it should come after the gpilot stuff. Note
>>> the SEE ALSO section is ordered first by manpage section number and
>>> then alphabetically, so it should look like "bar(1), foo(1), bar(3),
>>> foo(3), bar(5), foo(5)" for example. libpisync is also in the wrong
>>> alphabetic order.
>>> - Aren't there any online docs for these interfaces? References should
>>> be put in the "SEE ALSO" section.
> No, there aren't. Since this library is only for the application itself,
> nor for public use.
>
> Thanks,
> Jerry
>>>
>>> Brian
>>>
>>>
>>>
>>>
>>>
>>>
>>>> Thanks,
>>>> Jerry
>>>>
>>>> Brian Cameron wrote:
>>>>>
>>>>> Jerry:
>>>>>
>>>>>> These four libs are delivered with SUNWgnome-pilot, they are
>>>>>> missing originally. Please noete libgpilotdcm and
>>>>>> libgpilotdconduit are shadow manpages. Please review.
>>>>>
>>>>> gpilotd(1):
>>>>>
>>>>> - I would just say "gnome-pilot daemon" rather than "gnome-pilot
>>>>> gpilotd
>>>>> daemon"
>>>>> - I would remove "shipped with Gnome-Pilot package" in the DESCRIPTION
>>>>> - I'd say "that monitors" rather than "that monitor".
>>>>>
>>>>> - You say:
>>>>>
>>>>> Gnome-pilot has an API for creating conduits as well as a
>>>>> couple
>>>>> of default conduits, including one for backing up files, and
>>>>> one for installing files.
>>>>>
>>>>> I would say:
>>>>>
>>>>> Gnome-pilot has default conduits for backing up files and
>>>>> installing files. It also includes an API for creating conduits.
>>>>>
>>>>> - You say:
>>>>>
>>>>> > for example, the Evolution mail/calendar/memo PIM
>>>>> application
>>>>> > suite.
>>>>>
>>>>> I would make this a new sentence.
>>>>>
>>>>> - I would also include the new section 3 manpages in the "SEE ALSO"
>>>>> section. Also there seem to already be a manpage for
>>>>> gpilot-install-file.1. I would mention this in SEE ALSO as well.
>>>>>
>>>>> libgpilotd(3):
>>>>>
>>>>> - I would say "C interfaces" rather than "C interface". I would
>>>>> also change "gnome-pilot gpilotd daemon" to just "gnome-pilot
>>>>> daemon".
>>>>>
>>>>> - I would say "The gpilotd daemon monitors for pilot connections
>>>>> on one or more devices." instead of the first sentence of the
>>>>> DESCRIPTION. Note "connections" rather than "connects". No
>>>>> need to mention about the package.
>>>>>
>>>>> - I would also reword the "It has an API for creating conduits"
>>>>> sentence as I show above for gpilotd(1).
>>>>>
>>>>> - The SEE ALSO section should also mention gnome-pilot-install-file.1
>>>>>
>>>>> - Are there any API references installed to /usr/share/gtk-doc, or
>>>>> someplace else, perhaps online? If so, I would also mention a
>>>>> reference to the docs in the SEE ALSO section.
>>>>>
>>>>> Brian
>>>>
>>>
>>
>
