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) > > | <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 -- To UNSUBSCRIBE, email to [email protected] with a subject of "unsubscribe". Trouble? Contact [email protected] Archive: http://lists.debian.org/[email protected]
