Control: tags -1 +pending
On 2018-02-25 21:50:43, Adam Borowski wrote:
> On Sun, Feb 25, 2018 at 12:54:44PM -0500, Antoine Beaupré wrote:
>> On 2018-02-25 01:33:45, Adam Borowski wrote:
>> > Hi!
>> > As "undertime" is a command-line program that requires arguments to do
>> > anything useful, some description of how to use it would be required.
>> >
>> > Shipping such documentation as a man page would be greatly preferred
>> > -- and there's no other docs in the package anyway.
>>
>> There should be a README file in the package, and there's inline help
>> with the program with the `--help` flag.
>
> [~]$ dpkg -L undertime
> /usr/bin/undertime
> /usr/lib/python3/dist-packages/undertime-1.1.0.egg-info/*
> /usr/share/doc/undertime/changelog.gz
>
> ... so no README. I did manage to find --help, it's not that hard to
> guess,
... oops, looks like I forgot to ship those files... will fix.
> but the point of Unix systems standardizing on man pages is to eliminate the
> need for guessing.
True.
>> What, in particular, would you like to see in the manpage? This would
>> help in writing one (and I would welcome patches that would create one
>> as well).
>
> A copy of --help would be a fine first stab, almost adequate already.
Okay.
> One caveat that's worth documenting is that the time zone names are case
> sensitive (GMT not gmt) and that, while you can use names of major cities,
> they need to be given with an underscore rather than space (New_York rather
> than 'New York').
This might be better fixed in the code than the documentation. ;)
(Done.)
>> If there's enough interest, I would write this as Sphinx
>> documentation and make that generate the manpage, which seems the
>> shortest path between a simple text format (rst) and the mangled mess of
>> backslashes that is manpage format. ;)
>
> Hrm, nasty Python specific formats. I'd recommend something readable and
> intuitive, like POD. *duck*
Riiight. Might as well just write mdoc. :p
A.
--
Advertisers, not governments, are the primary censors of media content
in the United States today.
- C. Edwin Baker
