Re: Updated maint-guide contents, question on style
Osamu Aoki wrote:
[...]
>> This is the chapter I nearly submitted a wishlist bug-report for
>> almost a decade ago, since maint-guide claimed to cover every step in
>> the process of creating a simple Debian package, but turned out to
>> have a crucial hole in its instructions.
>
> You mean in Chapter 1:
(I don't know what it said all that time ago; I just remember
being wrongfooted.)
[...]
> This depends on how far we go into "every little". Besides, we should
> not dwell on corner cases. This was Josip's text. I do not think he
> does to the level you exected. I am more along
>
> * Please understand to keep this document focused.
> * Some thing should be left to the practice by the reader.
> * Something needs to be left out and people must check official docs.
Yes; as I said later, the main fix I would suggest is merely to
mention this as one of the specific types of program that a newbie
packager shouldn't pick. It would be nice if someday I could find an
"introduction to make for non-programmers", but I doubt anybody's ever
going to write one, and it wouldn't fit in maint-guide.
> Maybe we need to change this to: (Please proof this)
>
> | This document will explain all the important technical step for Debian
> | packaging by the example. Although you may perceive some contents to be
> | irrelevant at first, please be paitient and bear with us.
This document will explain all the important technical steps for Debian
packaging by example. Although you may perceive some of its contents to be
irrelevant at first, please be patient and bear with us.
or
Although some of its contents may seem
irrelevant at first, please be patient and bear with us.
[...]
>> (Come to that, nor does any documentation I've ever found; if you're
>> not familiar with the traditional C-programming workflow and the
>> problems make is designed to solve, but need to use it to automate a
>> quite different process, its manual is unintelligible.)
>
> "make" is easy example here for our target audience.
> You can do packaging without make.
You can't do policy-compliant Debian packaging without make. Policy
4.9 says the rules file *must* be an executable makefile; to create
targets in the rules file I need to speak make-ese. It may be true
that I'd only be creating a trivial, degenerate make system; but if
you don't already understand make, using it to automate a build that
doesn't *need* make is a frustrating task!
>> Now, filling in this missing step would take a lot of work by somebody
>> other than me, so as a stopgap I'll suggest the alternative of clearly
>> signposting the hole. Section 2.1 warns against picking a library,
>> daemon, or setuid program, and insists on executables being in binary
>> form; at present this looks like an oversight, but instead it could
>> explicitly advise against interpreted languages. I'm not sure what
>> justification it could offer for this, though.
>
> * command line binary executable using existing libraries.
> * interpreter based program.
>
> These are easier than libraries or daemons. This guide line is common
> sense thing.
Yes, helloworld.sh is simpler than helloworld.cc; but at present the
guidelines imply that you should avoid scripting languages because
they're complex:
# * The program should be in binary executable form; libraries are
# harder to handle.
The "binary" there is conflating two pieces of advice that have
different rationales. Maybe they should be fractionated out into
something like:
* The software should be in the form of an executable; libraries are
harder to handle.
* It should use a common compiled language and build system, since
this guide can't cover every obscure corner case.
>> Moving on... section 2.3 is "Free portable programs". I don't
>> understand this title (why isn't it something like "widely used build
>> systems"?),
>
> I can retitle as "Popular free protable build system".
Make that "Popular portable build systems"; "free" is redundant. It
also seems to require me to read it as "(portable build) systems"
rather than "portable (build systems)", which is odd, but at least
it's shorter than any other way of saying it that I can think of.
--
JBR with qualifications in linguistics, experience as a Debian
sysadmin, and probably no clue about this particular package
Reply to: