PLD-doc: devel-hints-en.txt, devel-hints-pl.txt - some fixes and consitency...

Sun Jan 24 21:09:29 CET 2016

Author: qboosh                       Date: Sun Jan 24 20:09:29 2016 GMT
Module: PLD-doc                       Tag: HEAD
---- Log message:
- some fixes and consitency improvement in "patching" section, added subsection regarding *-info patches

---- Files affected:
PLD-doc:
   devel-hints-en.txt (1.59 -> 1.60) , devel-hints-pl.txt (1.71 -> 1.72) 

---- Diffs:

================================================================
Index: PLD-doc/devel-hints-en.txt
diff -u PLD-doc/devel-hints-en.txt:1.59 PLD-doc/devel-hints-en.txt:1.60

--- PLD-doc/devel-hints-en.txt:1.59	Wed Apr 13 15:02:20 2011
+++ PLD-doc/devel-hints-en.txt	Sun Jan 24 21:09:24 2016
@@ -341,28 +341,29 @@
    cp -f /usr/share/automake/config.sub .
 
 9.1. Patching
-    All patches should be applied in %prep section using %patchN macros. 
-    For example:
 
-    %prep
-    %setup -q
-    %patch0 -p1
-    %patch1 -p0
+   All patches should be applied in %prep section using %patchN macros. 
+   For example:
+
+   %prep
+   %setup -q
+   %patch0 -p1
+   %patch1 -p0
    
-    One way of easy generating patches is using gendiff.
-    Prepare sources by running ("thrift" is example package):
+   One way of easy generating patches is using gendiff.
+   Prepare sources by running ("thrift" is example package):
    
    nice ./builder -v -bp thrift   
   
-   Copy orginal file contens inside  BUILD/ to files with postfix
+   Copy original file contents inside BUILD/ to files with postfix
    which will describe patch a little ( "cpp-link-fix" in example):
   
    cp  Makefile.am  Makefile.am.cpp-link-fix
   
-   Edit _orginal_ file (Makefile.am in example) to contents you need.
-   Generate patch (from outside of source of pacakge - in BUILD directory) by:
+   Edit _original_ file (Makefile.am in example) to contents you need.
+   Generate patch (from outside of source of package - in BUILD directory) by:
   
-   gendiff thrift-0.5.0/  .cpp_link_fix  > ../packages/thrift/thrift-cpp_link_fix.patch
+   gendiff thrift-0.5.0/  .cpp-link-fix  > ../packages/thrift/thrift-cpp_link_fix.patch
 
    Now one can check results of patch by finishing building rpm package:
    nice ./builder -v -bc --short-circuit thrift   
@@ -371,7 +372,7 @@
   
    If results are satisfactory add patch to spec:
   
-   Patch1:         %{name}-cpp_link_fix.patch0
+   Patch1:         %{name}-cpp_link_fix.patch
    %patch1 -p1
   
    Final step is check whole build in one step.  
@@ -379,6 +380,8 @@
   
 9.2. Endline character convertion in PLD CVS
 
+   [Note: git repositories are not affected by this conversion]
+
    CVS, at least PLD CVS, converts DOS ends of line (\r\n) to unix eols (\n).
    It may break some patches. If your patch does not apply after CVS commit /
    checkout, try to undos sources before patching using %undos macro. For
@@ -394,6 +397,23 @@
    %{__find} -name Makefile | xargs %undos
 
    Don't forget to add %undos BRs. See BuildRequires.txt for details.
+
+9.3. Info documentation unification/patching 
+
+   Most of packages containing Texinfo documentation in PLD are patched with
+   %{name}-info.patch. The patch usually does the following:
+   a) unifies @direntry formatting so that descriptions start in 41. column
+      if possible (it's best visible in main info/pinfo directory)
+   b) adds or modifies @dircategory tag consistent with other Texinfo documents
+   c) unifies program usage entries to be found as "(document)program."
+      (this differs from common GNU practice of naming these nodes as
+       "program Invocation" or "Invoking program")
+   d) (sometimes) removes part of document concerning programs not packaged in
+      PLD (e.g. locate+updatedb in findutils.spec)
+   Other changes (typos, syntax fixes, texinfo 5+ compatibility fixes etc.)
+   should be submitted upstream.
+   Some vendors accept patches from a) category (while the others don't care),
+   but categories b), c), d) are PLD-specific.
 
 10. Build process section (%build)
 

================================================================
Index: PLD-doc/devel-hints-pl.txt
diff -u PLD-doc/devel-hints-pl.txt:1.71 PLD-doc/devel-hints-pl.txt:1.72
--- PLD-doc/devel-hints-pl.txt:1.71	Thu Feb 24 21:52:25 2011
+++ PLD-doc/devel-hints-pl.txt	Sun Jan 24 21:09:24 2016
@@ -338,6 +338,8 @@
    builder -bp ignoruje BuildRequires. Przykładowo następująca komenda powinna
    się znaleźć w sekcji %build: cp -f /usr/share/automake/config.sub .
 
+9.1. Nakładanie łat
+
    W sekcji %prep nakładamy łatki na źródła korzystając z makr %patchN. Na
    przykład tak:
 
@@ -346,6 +348,41 @@
    %patch0 -p1
    %patch1 -p0
 
+   Jednym ze sposobów tworzenia łat jest użycie programu gendiff.
+   Źródła można przygotować uruchamiając (na przykładzie pakietu "thrift"):
+
+   nice ./builder -v -bp thrift
+
+   Następnie należy skopiować oryginalną zawartość plików BUILD/ do plików
+   z przyrostkiem opisującym jakoś łatkę (np. "cpp-link-fix"):
+
+   cp Makefile.am Makefile.am.cpp-link-fix
+
+   Następnie należy zmodyfikować _oryginalny_ plik (np. Makefile.am)
+   i wygenerować łatkę (z zewnątrz katalogu pakietu, tj. katalogu BUILD)
+   poprzez:
+
+   gendiff thrift-0.5.0/ .cpp-link-fix > ../packages/thrift/thrift-cpp_link_fix.patch
+
+   Następnie można sprawdzić wynik łatki kończąc kolejne kroki budowania pakietu:
+
+   nice ./builder -v -bc --short-circuit thrift   
+   nice ./builder -v -bi --short-circuit thrift
+   nice ./builder -v -bb --short-circuit thrift
+  
+   Jeśli wyniki są satysfakcjonujące, można dodać łatkę do pliku spec:
+  
+   Patch1:         %{name}-cpp_link_fix.patch
+   %patch1 -p1
+  
+   Ostatnim krokiem jest sprawdzenie całego procesu budowania w jednym kroku.
+   Można jednocześnie dodawać, modyfikować i testować wiele łatek jednocześnie
+   używając różnych przyrostków.
+  
+9.2. Konwersja znaku końca linii w CVS-ie PLD
+
+   [Uwaga: repozytoria git nie są dotknięte tą konwersją]
+
    CVS, przynajmniej nasz, automatycznie konwertuje końce linii DOS-owe (\r\n)
    na uniksowe (\n). W przypadku łatek taka zmiana często powoduje, że po
    scommitowaniu łatki a następnie pobraniu, łatka przestaje się nakładać.
@@ -363,6 +400,26 @@
 
    Pamiętaj, żeby dodać odpowiednie BR-y dla makra %undos takie, jak opisano w
    pliku BuildRequires.txt.
+
+9.3. Ujednolicenie/łatanie dokumentacji Info
+
+   Większość pakietów zawierających dokumentację w PLD ma zaaplikowaną łatkę
+   o nazwie %{name}-info.patch. Zmiany wykonywane w niej zwykle obejmują:
+   a) ujednolicenie formatowania wpisów @direntry, aby opisy zaczynały się
+      w miarę możliwości w 41. kolumnie (najlepiej jest to widoczne w głównym
+      katalogu info/pinfo)
+   b) dodanie lub zmodyfikowanie znacznika @dircategory dla spójności z innymi
+      dokumentami Texinfo
+   c) ujednolicenie nazw wpisów z opisami użycia programów, aby były dostępne
+      jako "(dokument)program."
+      (różni się to od częstej praktyki w projektach GNU, aby węzły te
+       nazywały się "program Invocation" albo "Invoking program")
+   d) (czasem) usunięcie części dokumentu dotyczącej programów nie
+      pakietowanych w PLD (np. locate+updatedb w findutils.spec)
+   Inne zmiany (poprawki literówek, składni, zgodności z texinfo 5+ itp.)
+   powinne być przekazywane do twórców z projektów zewnętrznych.
+   Niektórzy akceptują jeszcze łatki z kategorii a) (innych to nie
+   interesuje), ale zmiany z kategorii b), c) i d) są specyficzne dla PLD.
 
 10. Sekcja budowania (%build):
 
================================================================

---- CVS-web:
    http://cvs.pld-linux.org/PLD-doc/devel-hints-en.txt?r1=1.59&r2=1.60
    http://cvs.pld-linux.org/PLD-doc/devel-hints-pl.txt?r1=1.71&r2=1.72

