Re: Hello!

Julien Hardelin <jm.hard@xxxxxxxxxx> · Fri, 15 Sep 2017 07:50:41 +0200



    Welcome,
    

    Many chapters have to be updated, rebuilt or created. There is no
      complete list of what is to be done. You can find some indications
      in the "bug" list of Bugzila
      :https://bugzilla.gnome.org/buglist.cgi?bug_status=__open__&content=gimp%20manual&no_redirect=1&order=Importance&product=GIMP-manual&query_format=specific.
      Also when you have built the html files of the work in progress,
      you will find a What's new in GIMP-2.10 section.

    
    But the main way is to compare gimp-2.9.6 with the help html
      files.
    The Gimp manual has a long history. Unless you want to create a
      completely new manual, your work has to fit the existing document.
    I attach a How to contribute html file that summarizes my
      experience.
    

    Julien Hardelin

    
    Le 14/09/2017 à 17:27, Famiglietti,
      Andrew A a écrit :

    
      Hi Gimp Documentation List!

      
      I'm a professor in the English Department at West Chester
      University of Pennsylvania, and I'm planning to use Open Source
      Software documentation as a "real world" writing task for my
      Technical Writing Students this semester. I noticed your project
      was looking for documentation help and thought I would reach out.
      Some things you should know:
      

        - I'm not going to swamp you with student pull requests.
        Students will file their drafts with me, first, and then I will
        pass them on to you only if I think they have a reasonably good
        end product, and I have an ok from the project

        
        I was wondering:
      

        - If you would be interested in seeing the documentation drafts
        students produce

        - If there was any particular area of documentation you were
        particularly in need of
      

        Thanks so much for your time! 

        
           ---
            
               Andy Famiglietti,
                PhD
               Assistant Professor
                of English, West Chester University
               http://copyvillain.org
            
          
      _______________________________________________
gimp-docs-list mailing list
gimp-docs-list@xxxxxxxxx
https://mail.gnome.org/mailman/listinfo/gimp-docs-list

    
Title: 6. How to Contribute


          6. How to Contribute
        
        
          Chapter 3. First Steps with Wilber
           
        
            6. How to Contribute
          
        
    Welcome to the GIMP-Help team!
  
      
    This tutorial is intended for writing documentation. If you want to 
    translate the documentation or the user interface, 
    please go to "https://l10n.gnome.org/teams/xx" where "xx"  
    is your language code: ISO 639-1 language codes can be found at
    http://www.loc.gov/standards/iso639-2/php/code_list.php.
  
      
          Prerequisite
        
        
            Join our mailing list>
          
          
            You can join our mailing list at
          https://mail.gnome.org/mailman/listinfo/gimp-docs-list.
          Please, feel free to ask questions.
        
          
            Create a Local Working Copy of Code
          
          
          The GIMP help Manual is lodged in a central repository at
          http://git.gnome.org. Creating a local copy of this repository to work
          on makes sure that everyone can work on his own without fuzzing around
          into works of other contributors.
        
            
          As a newbie, you will access the git repository anonymously (without 
          an account). Open a terminal and type:
          git clone git://git.gnome.org/gimp-help-2.
        
            
          If you have a GNOME account, the command is:
          git clone ssh://yourusername>@git.gnome.org/git/gimp-help-2
          .
        
            
          This will create a “gimp-help-2” folder in your current
          directory. Be patient! That's a big download: about 700 MB.
        
          
            Installing your sandbox
          
          
          After downloading your local copy, run:
          cd gimp-help-2 then
          ./autogen.sh --without-gimp.
        
            
          When running ./autogen.sh, you can notice some not found packages, for
          example “checking for dblatex... no”. Most of them are
          related to PDF files and you have to install them before running
          ./autogen.sh again if you want to create PDF files.
        
          
            The gimp-help-2 folder
          
          
          The GIMP User Manual is maintained in the xml files of the
          “src” folder. These xml files are used by developers. 
        
          
          Workflow
        
        
            Writing
          
          
          The language is English (USA).
        
            
          To edit XML files, use your preferred text editor. Personally I use 
          Kate. You must set the editor for:
          
            
                English language.
              
                
                Indent with 2 spaces (the Tab key must move
                pointer by two spaces).
              
                
                Replace tabs with spaces (for compatibility with all text
                editors and web browsers).
              
                
                80 characters per line.
              
                
                Automatic spell checking with English (USA) for default 
                language.
              
                
          Source files are written in the XML language according to the DocBook
          DTD. DocBook specifications can be found at
          http://tdg.docbook.org/tdg/5.0/docbook.html.
        
            
          Don't be afraid. We don't use all these items and you will learn XML
          progressively reading existing XML files. For new files, please use
          the templates you can find in the gimp-help-2/docs/templates folder.
        
            
                  Note
                
                
            If you write a new file, you must add it in the src/gimp.xml file, 
            or in the XML file that calls it (for example, the 
            src/menus/edit.xml file calls undo.xml, redo.xml, fade.xml... and 
            so on).
          
                  
            Validating
          
          
          When you have finished writing, you must validate your work:
          
            
                In command line, for a single file, you can use: 
                xmllint --noout your-file.xml. This command 
                displays nothing if your file is OK. Else it indicates where 
                the 
                error is. This command is for quickly sorting an xml file out; 
                it can miss or may not find some errors.
              
                
                Else just run: make validate-en. You must
                get a “No error” message.
              
                  
                Else, a list of validity errors is displayed with line numbers 
                referring to the en.xml log file that you can find in the /log 
                folder.
              
                  
                Open this en.xml file in a text editor, type Ctrl+G and enter 
                the line number to jump to the concerned line in the en.xml 
                file. There,you will find the error.
              
                  
                if you have worked on several XML files, look above in the 
                en.xml file to find (in the “xml:base” field of 
                the “id” tag), in which xml file the error is. 
              
                  
                Fix the error. Don't forget to save the file and run 
                make validate-en again.
              
                  
                        Note
                      
                      
                  A frequent foolish mistake is editing the en.xml log file 
                  instead of the XML file.
                
                        
            Images
          
          
          You also have to manage screenshots. Here are some hints for 
          making good screenshots:
          
            
                reduce screenshot area as much as possible cropping the window
                manager borders and disabling the help button (you can do it
                in the preference dialog),
              
                
                set the image mode to indexed 255 colors
                Image → Mode → Indexed
              
                  
                This is not necessary for icons and if your image has only few 
                colors. In these cases, indexed images are bigger than 
                non-indexed.
              
                
                set print resolution to 144 ppi (not for small images like 
                icons). You can do this easily with GIMP from
                Image → Print Size...
              
                
                Export images in the PNG format.
              
                
          Don't include English text in images. Translators can't translate it 
          and many users don't like that. Use XML captions instead, or provide 
a 
          .xcf file in the docs folder, indicating 
          it by a comment in the XML file: "TRANSLATORS: there is a .xcf file 
for 
          this image in the docs folder."
        
            
          Icons for GIMP are in usr/share/gimp/2.0/icons. GTK icons are in 
          usr/share/gtk-doc/html/gtk2.
        
            
            To include an icon in the text:
          
            
          Three commands to manage your images:
          
            
                make check-image-resolutions-en: gives the
                references of images whose resolution is not 144 ppi.
              
                
                make check-images-en: give references of
                missing or orphaned images.
              
                
                mogrify units PixelsPerTrack -density 144x144 
                *.png to set the print resolution of all PNG images.
              
                
            Create HTML Files
          
          
          Once XML files have been validated, run make 
          html-en. Creating HTML files is important to have 
          an idea about what users will see. You will probably notice 
          some improvements to be made on your XML file.
        
            
          You can make an HTML draft (when the folder xml/en has been created 
          during validation) for a single source xml file, by running, for 
          instance, the command         
          make xml/en/concepts/brushes.draft. This create 
          the brushes-draft.html for the brushes.xml file. But images are not 
          embedded in draft files.
        
            
          You can also use yelp and run yelp 
          file:///your-file.xml.
        
          
            Sending your files
          
          
          When your files are ready:
        
            
                  You don't have a GNOME account
                
                
                if you don't have a GNOME account, you must find a 
correspondent 
                who accepts to "push" files for you; that will not be difficult 
                if you send a message to the list. Either you send your xml 
                files and the attached images in a compressed file, (in a tree 
                reproducing that of the scr and images folders if you send 
                several files to make your correspondent's task easier), or you 
                send a "patch" that you have to create.
              
                  
                Before creating a patch, you have to get all your xml files 
                and images in the index. Being in the gimp-help-2 folder, do 
                git status. If you have files in the 
                Untracked files section, run git add -A.
              
                  
                Then run diff --full-index --binary origine > 
                name-of-the-patch to create the patch.
              
                
                  You have a GNOME account
                
                
                  All being well, you know how to manage Git. There are many 
                tutorials for that on the Web.
              
                
          Annexes
        
        
            XML notes
          
          
                ID's
              
            
          ID's, which identify commands and are used when pressing the F1 key 
          in the GIMP interface, are in 
          https://git.gnome.org/browse/gimp/tree/app/widgets/gimphelp-ids.h
        
            
                XML Tags Examples
              
            
          procedure: in using/web.xml.
        
            
          table: in 
          toolbox/tools-painting.xml.
        
            
          programlisting: in 
          filters/web/slice.xml.
        
            
          segmentedlist: in 
          dialogs/path-dialog.xml for a n columns list.
        
          
            Parents and Children
          
          
          Here is a diagram I often use.
          
            
          Working under Windows
        
        
      If you are using Windows you have to install Cygwin or a similar program 
      to simulate Linux to be able to install the programs used in translation 
      or writing. This chapter will tell you how to install Cygwin on Windows 
      and what packages needed to work on gimp-help.   
    
        
      The first thing to do is downloading the “setup.exe” from 
      http://www.cygwin.com/ and save it on your computer. You 
      need this program every time you have to do changes in Cygwin, so save it 
      on a place easily to find, e.g. “D:/cygwin/cygwin.exe”.
    
        
      Open the program setup.exe by double-clicking on it. This will open the 
      start window. Click on the “Next” button to open a window 
      where you have to choose how to install Cygwin. The default setting is 
      “Install from Internet”. This means that the downloaded 
      files will be saved on your computer before the files will be used to 
      install Cygwin. This is the easiest way to do it.  
    
        
      In the next window you have to choose where to install Cygwin on your 
      computer. The default is C:\cygwin which is a good choice. Normally you 
      also chooses the installation for all users. 
    
        
      If you marked the “Download without Installing” in the 
      previous window you will instead get a window where you determines where 
      to save the files. This window will be the next window if you install 
      from internet.
    
        
      The next window is how the computer is connected to internet. Normally 
      you choose the default setting.
    
        
      In the window “Choose A Download Site” you will find lots 
      of sites to download from. You may choose any of those starting with 
      “http://”, but it is a good rule to select one near you. 
      The installation program makes a folder with the same name as the site 
      you downloads from. If you change site, all the previous downloads will 
      be downloaded again in the new folder. That is not a problem. Normally 
      the program remember the last site used the next time you open it.    
    
        
      The next window lists all package categories available in Cygwin. A 
      package contains programs or program parts to be used in Cygwin. You do 
      not need all of them. As you see, every category is followed by a symbol 
      and the word “Default”. This means that the installer 
      will only load the packages necessary to run a minimum version of Cygwin. 
      So go on and press the “Next” button and admire the progress 
      of the downloading in the next window.  
    
        
      When downloading and installing is finished your copy of Cygwin is ready 
      to be adapted to GIMP.
    
        
            Adapting Cygwin to use with GIMP documentation tools
          
          
          I am not able to guarantee that the procedure described here will 
          work for you. It is a resume of the way I did it. Tested on Windows XP 
          and Windows 7.
        
            
          To be sure that Cygwin will use your language and the char code used 
          in GIMP documentation I changed the batch file used to open Cygwin.    
          (After saving a copy of the original batch file.) If you used the 
          default installation you will find the batch file in 
          C:/cygwin/Cygwin.bat. Rewrite the batch file to
          
            
            @echo off

            C:

            chdir C:\cygwin\bin

            set LANG=[language-code].UTF-8

            bash --login -i  

          
            If you have put Cygwin in another location than the default, you 
            have to write the new path instead of “C:\cygwin\bin”   
            above. You may find your language code in 
            http://gcc.gnu.org/onlinedocs/libstdc++/manual/localization.html.    
   
  
          Then you are ready for the next step. Open “cygwin/startup.exe
          ” and click on “Next” until you reach the package 
          window. You need the following packages:
          
            
              Devel/automake 1.12

              Devel/gettext-devel

              Devel/gettext

              Libs/libxml2

              Libs/libxml2-devel

              Interpreters/m4

              Devel/make

              Devel/pkg-config

              Libs/libxslt

              Libs/libxslt-devel

              Python/python

              Python/python-libxml2

              Python/python-libxslt

              Text/docbook-xml45

              Graphics/ImageMagic

              ....../wget

              ....../dblatex

              ....../pngcrush             

          
          The first package to be installed is the “automake 1.12” 
          in the “Devel” category. Click on the + mark in front of 
          the category's name (Devel) to open the package list. Search down the 
          rightmost column to find the package name “automake 
          1.12”. 
          Click once on the word “Skip”. The text will change to 
          “1.12.3-1” which is the version number for the choosed 
          package. Do the same with the other packages in the list above. Some 
          packages will be marked “Keep” instead of “Skip
          ”. This means that these packages already are installed. Do 
          not alter these settings unless you know for certain that this 
          package should be deleted, or reloaded, or something else.  
        
            
          When you have marked all packages to be added to Cygwin you press 
          “Next”. You will then be told that the packages you 
          selected needs some additional packages. Accept this. When you 
          reaches the end of the updating, your Cygwin copy is ready for all 
          that stuff mentioned in the start of this side.
        
            
          Some packages, especially those needed for PDF, can't be found with
          setup.exe. You can try installing them from sources. You can use
          "wget url-to-the-package" to download the
          wanted package, but, as you have to know the url, the best way is
          browsing the web under Windows; download the package (usually a
          .tar.gz file) and copy-paste into the Cygwin folder.
        
            
          Then run tar -xvzf your-package to decompress
          the package.
        
            
          Go into the new folder and read the INSTALL file for instructions 
          about installation.
        
            
                  Note
                
                
            pngnq cannot be installed from sources under Cygwin (dark problems
            with the libz library).
          
                    
            The installation procedure to install docbook2odf is explained at

          
          If you run into problems as mysterious error messages and so one, 
          feel free to ask for help on the mailing list mentioned on the top of 
          this page.
        
          
          5.2. Examples 
          
            
           Chapter 4. Getting Unstuck
        
      
      Report an error in Bugzilla
    
    
_______________________________________________
gimp-docs-list mailing list
gimp-docs-list@xxxxxxxxx
https://mail.gnome.org/mailman/listinfo/gimp-docs-list

	Note
	If you write a new file, you must add it in the src/gimp.xml file, or in the XML file that calls it (for example, the src/menus/edit.xml file calls undo.xml, redo.xml, fade.xml... and so on).

	Note
	A frequent foolish mistake is editing the en.xml log file instead of the XML file.