Re: Manpage pyksoko, could you have a look
manuel wrote:
> I'm currently in the process of packageing pyksoko for the PAPT.
>
> Its my first package so everything is quite new for me. The PAPT
> recommended that you have a look at the manpage.
>
> Could you read over the manpage and give some hints please.
Okay.
[...]
> .SH NAME
> pyksoko \- logic game with KDE sokoban skin/levels based on sokoban
Is it a "logic game based on sokoban" or does it have "levels based
on sokoban"? And what's going on in the middle there with that
"skin/levels" part? Reading ahead I deduce you mean
pyksoko \- logic game based on skoban with skin and levels from KDE
But with only one skin and multiple levels that's still a bit
awkward. Couldn't you just trim it down to:
pyksoko \- logic game based on KSokoban
and leave the details for later?
> .SH DESCRIPTION
(What no SYNOPSIS? I've inserted a minimalist one, though its nroff
may need tweaking.)
> This manual page documents briefly
> .B pyksoko
> A clone of the sokoban game with the skin
> of the KSokoban game who was shipped with KDE 3.5.x.
> You don't need KDE dependencies for it.
Drop the meta-documentation and just get on with the documentation.
The dependency information is also pointless by the time I'm reading
the man page. Instead it would be nice if it could expand a little
on what kind of thing sokoban is.
pyKsoko is a clone of the warehouse block-shifting puzzle game
sokoban, using a default skin taken from the KSokoban shipped with
KDE 3.5.x.
(Declaring "pyKsoko" the canonical capitalisation makes the name of
the user config directory less objectionable.)
> There is also a modern warehouse skin and
> the design is based around a warehouse.
> The game has over 5000 Levels.
I'm not quite sure what that first sentence is trying to say. Isn't
sokoban always "based around a warehouse"? How does a modern
warehouse look different from an old-fashioned one?
Common nouns like "levels" aren't normally capitalised in English.
The game also has a "modern" skin, and over 5000 levels.
(Or does that need to be ``modern'' or something?)
>
> You can download background music for the game on the homepage.
> See http://pyksokoban.sourceforge.net/ for further details.
Background music for the game can be downloaded from its
homepage.
> .SH FILES
> .I ~/.pyKsoko
> .RS
> User configuration and saved games
↑
Okay, but you need a full stop there.
> .SH BUGS
> If you find some please report them. See http://pyksokoban.sourceforge.net/ for further details.
The "how to report bugs" text on the sourceforge page points people
at http://eganglion.com/projects/pyksoko, but that's a dead link.
There's no useful information here, so cut the section.
> .SH "SEE ALSO"
> .BR python (1)
Why would a fan of KDE-based sokoban clones care about Python?
Maybe this is where the http://pyksokoban.sourceforge.net/ link
should be.
> .SH AUTHOR
> pyksoko was written by Manuel Soukup.
> .PP
> This manual page was written by Manuel Soukup <linuxuser-sky@gmx.de>,
> for the Debian project (and may be used by others).
Cut the comma.
--
JBR with qualifications in linguistics, experience as a Debian
sysadmin, and probably no clue about this particular package
.\" Hey, EMACS: -*- nroff -*-
.\" First parameter, NAME, should be all caps
.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
.\" other parameters are allowed: see man(7), man(1)
.TH PYKSOKO 6 "July 13, 2010"
.\" Please adjust this date whenever revising the manpage.
.\"
.\" Some roff macros, for reference:
.\" .nh disable hyphenation
.\" .hy enable hyphenation
.\" .ad l left justify
.\" .ad b justify to both left and right margins
.\" .nf disable filling
.\" .fi enable filling
.\" .br insert line break
.\" .sp <n> insert n+1 empty lines
.\" for manpage-specific macros, see man(7)
.SH NAME
pyksoko \- logic game based on KSokoban
.SH SYNOPSIS
.B pyksoko
.SH DESCRIPTION
pyKsoko is a clone of the warehouse block-shifting puzzle game
sokoban, using a default skin taken from the KSokoban shipped with
KDE 3.5.x. The game also has a "modern" skin, and over 5000 levels.
Background music for the game can be downloaded from its homepage.
.SH FILES
.I ~/.pyKsoko
.RS
User configuration and saved games.
.SH "SEE ALSO"
.BR http://pyksokoban.sourceforge.net/
.SH AUTHOR
pyKsoko was written by Manuel Soukup.
.PP
This manual page was written by Manuel Soukup <linuxuser-sky@gmx.de>
for the Debian project (and may be used by others).
Reply to: