[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Re: Updated maint-guide contents, question on style


Thanks for your work.

On Wed, Apr 20, 2011 at 11:30:51AM +0100, Justin B Rye wrote:
> Onward to chapter two.  I'm trying to cut down on editing glitches by
> previewing the output in xmlcopyeditor; any tips on less painful
> methods would be appreciated.

I usually rely on vim and building html file

 $ make index.en.html

> 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:
| This document will explain every little (at first maybe irrelevant)
| step, and help you create that first package, and to gain some
| experience in building the next releases of that and maybe other
| packages later on.

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.

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.

> If I want to Debianise some
> C program that I've found on Freshmeat, everything's fine.  But if
> I've got a ~/bin directory full of handy scripts that I've written in
> some interpreted language, and I want to turn *those* into a .deb, I'm
> out of luck - helloworld.sh ought to be simplest imaginable
> Debianisation project, but maint-guide insists on starting with a
> "make install", and gives no guidance on the step of *creating* an
> appropriate "upstream tarball"!

Hmmm.  Should I say you create upstream tarball just with helloworld.sh
in it.  Then install it to /usr/bin/helloworld (using .sh suffix is not
recommended practice for programs in /bin as I understand current
practive) using install command in debian/rule under install target?

If you are OK with helloworld.sh as command name, you can just install
it by creating debian/install file.

You do not need Makefile in tarball.

> (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.

> 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.

> 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".

> and I don't completely understand the diagrams.  Do the
> lines from the bottom indicate "these commands are also somehow
> involved in the process", or what?

Explaining this will be a full book.  Points to be made in this section are:

 * If you find your upstream using autotool, get help from the references.
 * If you wonder about the work flow, get some feel from diagram.  
 * I know you do not get what it exactly means. This is just outline.
   You need to read the referenced documents.  

If you have short additional text suggestion to close gap, let me know.

> Section 2.4 ("Package name and version") might need a transfusion
> from 1.5, but for now I'm just fixing up the existing version.

I agree.  1.5  should be split and merged into here and 1.1

Let's discuss this with other mail.

Your patches are applied.


Reply to: