Attention ports committers

[joeb]

-----Original Message-----
From: rea at codelabs.ru [mailto:rea at codelabs.ru]On Behalf Of Eygene Ryabinkin
Sent: Friday, January 14, 2011 4:46 PM
To: joeb
Cc: ports at freebsd.org
Subject: Re: Attention ports committers

Good day.

Fri, Jan 14, 2011 at 01:18:52PM -0500, joeb wrote:
> I would like to draw the attention of a ports committer to port
>
> http://www.freebsd.org/cgi/query-pr.cgi?pr=ports/148777
>
> If it needs further work please provide feedback.

A couple of things about the port:
 - you can just use plain SF instead of a long to type
   ${MASTER_SITE_SOURCEFORGE}; moreover, plain SF/${PORTNAME}
   and no MASTER_SITE_SUBDIR will work too and save you
   one more line;
 - share/examples/qjail in the pkg-plist is better spelled
   as %%EXAMPLESDIR_REL%%; and its ${PREFIX}/share/examples/qjail
   in the Makefile should really be ${EXAMPLESDIR}; also
   you can consider using PORTEXAMPLES to use port's procedures
   to install the examples and to avoid installing them when
   NOPORTEXAMPLES is set;
 - it is better to remove the commented DISTFILES, since
   it is not needed thus just adds the visual clutter;
 - pkg-descr is a way too chatty (in my taste); it can be
   definitely stripped down to provide the idea about
   what qjail is and the whole text can be put to the
   project's Web site;
 - you can put your rc.d script into USE_RC_SUBR inside
   the Makefile; just put your scripts into WRKDIR during
   the build phase; this will enable your port to survive
   any modifications to the process of installation of
   the rc.d scripts, because they will be handled by the
   ports subsystem;
 - pkg-message can be stripped down as well: first line
   looks redundant, since people already know why they
   had installed the port; the other two lines, perhaps,
   can be condensed into "Read qjail-intro(8) for to get
   started."  The said manual page has reference to the
   qjail(8), so people will know what to do after reading
   the introduction.

And please, please, please, try to put your shar(1) archive somewhere
to the Web and add the link to the PR: mail over gnats if not
uuencoded properly makes attachments with partial quoted-printable
stuff left, so download of, for example,
  http://www.freebsd.org/cgi/query-pr.cgi?prp=148777-3-shar&n=/shar-3.sh
will give a non-working shar(1) archive for starters and when '=0A='
will be removed, one will need to dance with the QP '=' characters,
newlines and alike.


May I also add, your software's manual pages can be improved:
 - don't insert empty lines into the groff files, use the
   lone dot if you want the visual separator inside the
   groff sources;
 - use standard macros like .Pa, .Xr, .Nm, .Qq and others
   instead of doing bold font, quoting and other stuff by hand;
 - avoid unneeded usage of the bold attribute; for example,
   qjail-intro(8) needs no bold for the "4th generation",
   "user friendliness" and other stuff;
 - start each sentense inside the manual source from the
   new line: this will provide two spaces between sentences
   in the formatted manual pages and will ease the diffs
   between revisions of the makefile (for you and other
   developers of the qjail, because this way changes in the
   manual pages will show up in the diff output only inside
   their own sentenses; they won't have the parts of other
   sentences in the + and - lines and that's good);
 - you have many trailing spaces; whilst they typically do
   not harm, why to keep them?


And for the qjail scripts themselves:
 - currently qjail is a single block with no subroutines;
   it _may_ be better to split it into logical parts,
   because it will be easier to read, navigate and understand
   for Other People (TM) ;))
 - perhaps you'll be able to use exit codes from sysexits(3).
 - what does jail2 rc.d script?  It terribly reminds me
   /etc/rc.d/jail and diffing the two one finds mostly
   cosmetic differences.  So, what's the point of having
   jail2 at all?


Sorry for a long letter and slightly mentorish tone: meant
no offense, just wanted to improve the stuff.
--
Eygene Ryabinkin                                        ,,,^..^,,,
[ Life's unfair - but root password helps!           | codelabs.ru ]
[ 82FE 06BC D497 C0DE 49EC  4FF0 16AF 9EAE 8152 ECFB | freebsd.org ]


WOW  Eygene Ryabinkin you sure missed the point of my post.
Your forensic investigation of my port is far outside the review of the make
file to commit the port.
So lets get back on task.
Scrubbing through your email content I only see you voicing your personal
preferences without any makefile statement errors, which would make the
Makefile invalid. This is a very simple Makefile so lets not make a mountain
out of a molehill. The port description is within the max size and is very
detailed on purpose. I plan to keep it that way.
The whole point of the post is that I am not a port Makefile coder. I wrote
a script for jails and it has taken longer to get the Makefile correct then
the coding of the original qjail script.  If the install of the RC_SUBR
script can be done in a more reliable way then what I need is the Makefile
statements to perform this action so I can update the port (shar) file with
them.
The goal here is to get this port committed, not waste time trying to teach
me the secret internal details of port makefiles construction.
I hope you see and comprehend the task and goal. Thank you for your
attention.
Joe