Re: Question on title and explanation of shuffles

[Osamu Aoki <osamu@debian.org>]

Hi,

I applied your patch and I have questions.

On Sat, Apr 30, 2011 at 06:28:58PM +0100, Justin B Rye wrote:
> Oops, I forgot the attachment on my last message, so I'll confuse
> things by adding it to this one.
> 
> > I was making all section title of be followed by file(s) in Chapter 4
> > and 5.  You kept "file" for all titles in Chapter 4 and 1 title in
> 
> Did I?  No, surely I took them out in Chapter 4.  5.15 looks like an
> oversight.

I now realize I may not have applied patch for Chapter 4.  Did you send
me one which I overlooked?  Can you resend it to me.  i could not find
one on this mailing list.  Sorry.
 
> > Chapter 5.  But you removed "file" from most titles in Chapter 5.
> > 
> > Any reason?  What do you suggest to make some consistency?
> 
> This was tricky.  Partly it was to avoid falling into the trap of
> talking about a "'control' file" (as opposed to "control file");
> partly it was because when you're introducing a file whose name the
> reader  isn't expected to recognise it's more idiomatic to refer to it
> as "the file 'package.manpages'" (whereas if the name is
> well-understood and helps the reader identify what kind of file it is,
> it's more idiomatic to say it as "the README file").  Likewise "put it
> in the directory ~/.shfqk" but "put it in the /tmp directory".

Simple question here:
 5.15. package.manpages file
Should I remove "file" here.  I think so.

A bit more involved question:
Certainly it is tricky.  
Your discussion is for the style in the content.  I am wondering if it
is better to have "file" in title to be crystal clear.  In order to keep
translation consistent, I intentionally added "file(s)" and "command" to
the keyword only titles after marking them properly with tags.

  http://www.debian.org/doc/manuals/maint-guide/index.en.html

> Of course, I was encouraged by the fact they're all wrapped in
> <filename> tags.

thanks.

> --- maint-guide.en.dbk.pristine	2011-04-30 12:52:45.588927791 +0100
> +++ maint-guide.en.dbk	2011-04-30 18:09:40.025258209 +0100
>  <para>
> -If you are making a Debian specific package without an upstream program instead, 
> -typical workflow of the Debian package building is simpler.
> +If instead you are making a Debian-specific package with no upstream, the
> +typical workflow of Debian package building is simpler.
>  </para>

I understand this but this colloquial insertion of "instead" may confuse
non-native readers.  How bad is the following alternative?

  Instead, if instead you are making a Debian-specific package with no
  upstream, the typical workflow of Debian package building is simpler.

> -  <listitem><para>single binary package, arch = all (executables written in the POSIX shell language)</para></listitem>
> -  <listitem><para>single binary package, arch = all (executables written in interpreter languages)</para></listitem>
> +  <listitem><para>single binary package, arch = all (executables written in an interpreted language such as POSIX shell)</para></listitem>

I get your point but I erased too much.  Since POSIX shell is easier
than Perl and Python, I had:

  <listitem><para>single binary package, arch = all (executables written in the POSIX shell language)</para></listitem>
  <listitem><para>single binary package, arch = all (executables written in interpreter languages such as Perl and Python)</para></listitem>

or

  <listitem><para>single binary package, arch = all (executables written in the POSIX shell language)</para></listitem>
  <listitem><para>single binary package, arch = all (executables written in Perl and Python)</para></listitem>

Any other languages are a bit more complexities.  What should I do?

> -There is another old Latin saying: <emphasis>Fabricando fit fabe</emphasis>
> -(Practice makes perfect).  It is <emphasis>highly</emphasis> recommended to
> -practice and experiment all the steps of Debian packaging with simple packages
> +There is another old Latin saying: <emphasis>fabricando fit faber</emphasis>
> +(practice makes perfect).  It is <emphasis>highly</emphasis> recommended to
> +practice and experiment with all the steps of Debian packaging with simple packages
>  while reading this tutorial.  A trivial upstream tarball

Should I change this to "There is an old Roman saying ..." as you
mentioned in the other place?

Osamu