Hi, With aftermath of the earthquake, I am a bit tired with crowded commuter train ....
On Mon, Mar 14, 2011 at 07:34:21PM +0100, Innocent De Marchi wrote: > Hi Osamu, > > Please respond quickly to my suggestions. > > > > > | --- maint-guide.en.sgml 2011-01-30 17:25:45.000000000 +0100 > > | +++ maint-guide.en-original_contributions.sgml 2011-01-30 > > 18:57:37.000000000 +0100 > > | @@ -96,8 +96,9 @@ > > | <p>Newer versions of this document should always be available online at > > | <url name="http://www.debian.org/doc/maint-guide/"; > > id="http://www.debian.org/doc/maint-guide/";> > > | and in the <package/maint-guide/ package. > > | - <!-- Translation in <this language> is also available in the > > | - <package/maint-guide-xy/ package. --> > > | + The translations (perhaps without upgrading to the latest version of > > the > > | + original in English) are distributed in the package > > <package>maint-guide-xx</package> > > | + (where xx is the language code). > > > > This one will be dealt a bit differently for translation. You will see new > > easier translation specific addendum method in my updated build script. > > OK > > > > > | @@ -268,7 +270,10 @@ > > | > > | <item><strong>source package</strong>: A source package is a set of > > files > > | which contain code and data which you can compile and process into > > execution > > | - programs and formatted documents. It usually comes as a combination of > > | + programs and formatted documents. > > | + <footnote><p>This document is the result of processing a > > <file>.po</file> file format > > | + to get a <file>pdf</file> file or a set of files in HTML > > format.</p></footnote>. > > | + It usually comes as a combination of > > | <file>*.orig.tar.gz</file>, <file>*.debian.tar.gz</file> (or > > | <file>*.diff.gz</file>), and <file>*.dsc</file>. Some other archive > > and > > | compression methods may be used, too. > > > > If I were to add this, "processing a <file>maint-guide.en.dbk</file> file > > and > > <file>maint-guide.??.po</file>" should be the words to describe source files > > for the translation. I see your thought to address specifics for this > > package. > > But is this really essential to mention this? > > You have more experience in this, your decision will be successful > > > > > | @@ -287,7 +292,7 @@ > > | <list> > > | > > | <item><strong>upstream author</strong>: The person who made the > > original > > | - program. > > | + program (or original documents in the case of documentation packages). > > | > > | <item><strong>upstream maintainer</strong>: The person who currently > > | maintains the program. > > > > Hmmm... you really want to explain how this doc package is packaged. But > > this > > document is more about execution program package. Putting too much > > information > > tends to loose focus and confused audience. > > OK. > > > > > | @@ -310,7 +315,7 @@ > > | > > | </list> > > | > > | - <p>There are several version names used around Debian. > > | + <p>There are several version names (see <ref id="namever">) used > > around Debian. > > | > > | <list> > > | <item><strong>upstream source version</strong>: The upstream source > > version is referred as <tt><var>version</var></tt>. > > > > Link to <ref id="namever"> is a good idea. But link to > > http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-Version > > is something needed too. How to get them all linked nicely.. let me > > think... > > OK. > > > > > | @@ -350,7 +356,9 @@ > > | <file>/usr/share/doc/debian</file>, <file>&autotools-dev;</file>, > > | <file>/usr/share/doc/<var>package</var>/*</file> > > | files and the <prgn>man</prgn>/<prgn>info</prgn> pages for all the > > programs mentioned in this document. > > | - See all the information at <url id="&nm-home;">. > > | + See all the information at <url id="&nm-home;"> > > | + <footnote><p>restricted access to persons who are in the program > > | + to access to DD or DM.</p></footnote> and <url id="&mentors-faq;">. > > | <p>Making a small test package is good way to learn details of > > packaging. > > | Inspecting existing well maintained packages is the best way to learn > > how other > > > > <!ENTITY nm-home "http://nm.debian.org/";> > > > > &newmaint; is part of &nm-home;. &mentors-faq; is extensive source of > > info. I > > do not want to duplicate in this way. It is good idea to mention > > &mentors-faq; > > though. Let me think. > > OK. > > > > > I do not understand your addition of <footnote>...</footnote>. I think you > > try > > to say something along: > > > > || See all the information at <url id="&nm-home;"> and and > > || <url id="&mentors-faq;"> to gain upload access to the Debian archive as > > DD or > > || DM. > > > > OK. > > > > > | @@ -358,12 +366,14 @@ > > | > > | <p>If you still have questions about packaging that you couldn't find > > answers to > > | in the available documentation and web resources, you can ask them on > > the Debian Mentors' mailing list > > | - at <url id="http://lists.debian.org/debian-mentors/"; > > name="[email protected]">. The more experienced Debian > > | + at <url id="http://lists.debian.org/debian-mentors/"; > > name="[email protected]"> > > | + and the IRC #debian-mentors (may have a IRC of mentors in your > > language). > > | + The more experienced Debian > > | developers will gladly help you, but do read at least some of the > > | documentation before asking a question! > > | > > | <p>See <url id="http://lists.debian.org/debian-mentors/";> for more > > | - information about this mailing list. > > | + information about this mailing list and the IRC channel > > #debian-mentors. > > | > > | <p>When you receive > > | a bug report (yes, actual bug reports!), you will know that it is time > > for you > > > > I got your point on IRC. But inclusion of "...mentors in your language" > > can be > > done a bit differently. I will think about it. > > OK. > > > > > | @@ -389,7 +399,8 @@ > > | > > | <chapt id="first">First steps > > | > > | - <p>Let's try to make your own package (or, better even, adopt an > > existing one). > > | + <p>Let's try to make your own package (or, better even, adopt an > > existing one, > > | + see <url id="http://wnpp.debian.net/"; name="Debian Packages that Need > > Lovin'">). > > | > > | <sect id="choose">Choose your program > > | > > > > I see your point. But following "2.1 Choose your program" list this and > > more. > > Isn't this too much duplication? > > Yes, If it is true > > > > > > | @@ -406,8 +417,9 @@ > > | <url name="Debian QA Group" id="http://qa.debian.org/";>, you may > > | be able to pick it up if it's still available (check the ownership > > status > > | at <url name="Debian Bug report logs: Bugs in package wnpp in > > unstable" id="http://bugs.debian.org/wnpp";>). > > | - You may also adopt a package for which the corresponding maintainer > > has filed > > | + You may also adopt a package for which the corresponding maintainer > > (or a DD) has filed > > | a "Request for Adoption" (<strong>RFA</strong>). > > > > This could be DM. So let's leave this without "(or a DD)" as was. > > OK. > > > > > | + See <url id="http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=594398";> > > for an example. > > > > Can you elaborate why you picked this example from other possible > > candidates? > > For no particular reason. I was looking to adopt some orphan package > and put this link. Surely there are other more appropriate! > > > > > | <p>Several different views of orphaned or RFA'ed packages are > > available at: > > | <list> > > | @@ -427,12 +439,27 @@ > > | You can do that in various ways. > > | <list> > > | <item>taking over orphaned, yet actively used, packages > > | + (look at the Popularity Contest Stats of the package in > > | + <url id="http://qa.debian.org/popcon.php";>) > > > > popcon gives us popularity but this interface is not the best entry to find > > actively used packages. > > Yes, I put some other link. > > > > > | <item>joining <url name="packaging teams" > > id="http://wiki.debian.org/Teams";> > > | <item>triaging bugs of very popular packages > > | <item>preparing <url name="QA or NMU uploads" > > id="http://www.debian.org/doc/developers-reference/pkgs.html#nmu-qa-upload";> > > | + <footnote><p>QA packages are maintained by the Debian Quality Group > > | + and they are orphans, and NMU are packages that do not currently > > | + have an maintainer.</p></footnote>. > > > > You insist to put this dspite I have link to "5.11.6. NMUs vs QA upload" in > > developers-reference. > > OK. > > > > > | </list> > > | > > | - <p>If you are able to adopt the package, get the sources (with > > something > > | + <p>If you are able to adopt the package, get the sources > > | + <footnote><p>The most direct way to adopt an orphaned package > > | + is to consult the list of orphaned packages <url > > id="http://wnpp.debian.net/?type[]=O&project=&description=&owner[]=yes&owner[]=no&col[]=dust&col[]=type&col[]=description&col[]=installs&sort=project";>. > > | + In these lists, package name refers directly to the bug report > > | + states that as an orphan. If you decide to adopt a package, > > | + send an email to the list with the number of bug report requesting > > | + the change of title of the error report > > | + (see <url id="http://www.debian.org/devel/wnpp/index.html#howto-o";>). > > | + With this notification, the other contributors know that you're > > | + working on the package.</p></footnote> > > | + , get the sources (with something > > > > I see your point to explain more around here. Quite frankly, this > > maint-guide > > is not primary place to describe NMU nor WNPP nor DM process. I think we > > should not duplicate too much contents. That will lead to unmaintainable > > document. This should only give pointer to such info and this should focus > > on > > what it is good .... technical aspect of simple packaging. Let me use this > > as > > reference and trim them down a bit. > > Yes, but for people starting out, this type of information (without > having to consult other sources) may be useful. But you can cut the > text: no problem. > > > > > | like "<tt>apt-get source <var>packagename</var></tt>") and examine > > them. This document > > | unfortunately doesn't include comprehensive information about adopting > > | packages. Thankfully you shouldn't have a hard time figuring out how > > the > > | @@ -526,7 +553,7 @@ > > | unpack it with appropriate tools and repack it, too. > > | > > | <p>As an example, I'll use a program called <prgn>gentoo</prgn>, an X > > GTK+ file > > | - manager.<footnote>This program is already packaged. Current version > > 0.15.3 has changed > > | + manager.<footnote>This program is already packaged. Current version > > 0.19.8 has changed > > | substantially from the version 0.9.12 in the following > > examples.</footnote> > > > > Thanks for finding this out. Since 0.19.8 may not be "Current", we may > > want to use "More recent". > > Then we do not need to update this version number often. > > Yes, update version is a drag. Maybe they could put a link to PTS > (http://packages.qa.debian.org/g/gentoo.html) Good suggestion ... need some text changes ... > > | <p>Create a subdirectory under your home directory named > > <file>debian</file> or <file>deb</file> > > | @@ -555,7 +582,11 @@ > > | directory; you won't be doing that, but more on that later in <ref > > | id="destdir">). > > | > > | - <p>Simple programs come with a <file>Makefile</file> file in them and > > can be > > | + <p>The process varies from program to program, but most modern > > | + programs come with a script <file>configure</file> to configure > > | + the sources for your system and ensures that the system is able > > | + to compile. > > | + Simple programs come with a <file>Makefile</file> file in them and can > > be > > | compiled simply with "<tt>make</tt>". Some of them support > > > > How about ...: > > > > <p>The build process of programs varies from program to program. Simpler > > programs come with a <file>Makefile</file> file in them. Many modern > > programs > > come with a script <file>configure</file> which creates a > > <file>Makefile</file> > > file customized for your system upon its execution. These programs can be > > build simply with "<tt>make</tt>" using the <file>Makefile</file> file. > > OK. > > > > > <p>Some of them support > > | "<tt>make check</tt>", which runs included self-checks. Installation > > to the > > | destination directories is usually done with "<tt>make install</tt>". > > | @@ -759,7 +790,10 @@ > > | <tt>--addmissing</tt> option again in a Debian package > > | source tree. > > | > > | - <p>Updating an existing package may get complicated since it may be > > using > > | + <p>Please note that you should run <prgn>dh_make</prgn> only once, > > | + and not behave correctly if you do it again in the same directory > > | + with the <file>debian</file> directory already generated. > > | + Updating an existing package may get complicated since it may be using > > | older techniques. Please stick with fresh packaging cases for now to > > learn > > | basics. I will come back to explain it later in <ref id="update">. > > > > I intentinally removed this warning... We have -a, --addmissing option now. > > OK. > > > > > | @@ -829,7 +863,16 @@ > > | install gentoorc-example $(HOME)/.gentoorc > > | </example> > > | > > | -<p>Ask <prgn>quilt</prgn> to refresh the patch to create > > <file>debian/patches/fix-gentoo-target.patch</file> and add its description. > > | +<p>Ask <prgn>quilt</prgn> to refresh the patch to create > > <file>debian/patches/fix-gentoo-target.patch</file> and add its description > > | +<footnote><p>It is advised that after the execution of each order, > > | +you carefully consider the changes. In this example, the > > | +<file>debian/patches/fix-gentoo-target.patch</file> file is generated: > > | +which is a text file that contains the changes into the > > | +<file>Makefile</file> file. Lines to delete are preceded by > > | +a sign <tt>-</tt> and then the new lines are preceded by a <tt>+</tt>. > > At the head > > | +of the patch file is the description of the patch. The descriptions > > | +must be in English. See <url name="Patch Tagging Guidelines" > > id="http://dep.debian.net/deps/dep3/";> > > | +for more details.</p></footnote>.. > > > > I like dep3 reference but explanation of patch seems exessive. > > OK. > > > > | <item>The source follows the Filesystem Hierarchy Standard (FHS). > > | </list> > > | <p>Programs that use GNU <prgn>autoconf</prgn> <em>automatically</em> > > follow > > | @@ -901,6 +945,13 @@ > > | strings like > > | > > <tt>/home/me/deb/<var>package</var>-<var>version</var>/usr/share/<var>package</var></tt> > > | into the package file. > > | + The <file>.deb</file> files are compressed files. If you look > > | + the <file>.deb</file> file with a compressed files management program > > | + you will see a zip file containing "data.tar.gz" which contains > > | + a replica of the directory structure starting at the root directory. > > | + The analysis of the contents of the "debian" directory after > > | + the construction of the <file>.deb</file> file and the content > > | + of the <file>.deb</file> package file can you help to understand the > > process. > > > > Let me think what to do. I intentinally left this technical aspect out > > since > > readers are expected to read dpkg document etc. > > OK: > > > > > | <p>Here's the relevant part of <package>gentoo</package>'s > > | <file>Makefile</file> file > > | @@ -955,10 +1006,13 @@ > > | $ grep -nr -e 'usr/local/lib' --include='*.[c|h]' . > > | </example> > > | > > | - <p><prgn>grep</prgn> will run recursively through the source tree and > > tell > > | - you the filename and the line number for all matches. > > | + <p><prgn>grep</prgn> will run recursively through the source tree > > | + searching files with <tt>.c</tt> and <tt>.h</tt> extension and show > > | + you the filename and the line number when it finds a match with the > > | + chain <file>usr/local/lib</file>. > > > > With s/chain/string/, this is good suggestion for novice. Do we need to be > > so > > wordy for "grep", that is somehing I wonder. Why not read manpage if the > > reader is new maint candidate... > > OK. > > > > > | <p>Edit those files and in those lines replace <tt>usr/local/lib</tt> > > with <tt>usr/lib</tt>. > > | + Can be done automatically with this order: > > > > How aboout: > > > > This can be done automatically as follows: > > > > (We Japanese and Spanish people tend to drop obvious subject words.... but > > Anglophone does not like it.) > > True! > > > ==== Following are not checked well ==== > > OK. > And continue in the next chapter > > Regards! > > I. De Marchi Good night ... I need to wake up 4:30 in the morning for commute ... -- To UNSUBSCRIBE, email to [email protected] with a subject of "unsubscribe". Trouble? Contact [email protected] Archive: http://lists.debian.org/[email protected]
