included"> ]> Εγχειρίδιο GTK-Doc 1.24.1 Εγχειρίδιο χρήστη για προγραμματιστές με οδηγίες για τη χρήση του GTK-Doc. Chris Lyttle
chris@wilddev.net
Dan Mueth
d-mueth@uchicago.edu
Stefan Sauer (Kost)
ensonic@users.sf.net
Έργο GTK-Doc
gtk-doc-list@gnome.org
 2000, 2005 Dan Mueth και Chris Lyttle 2007-2019 Stefan Sauer (Kost) Χορηγείται άδεια αντιγραφής, διανομής και/ή τροποποίησης του παρόντος εγγράφου υπό τους όρους της έκδοσης 1.1 της Ελεύθερης Άδειας Τεκμηρίωσης GNU (GFDL), ή οποιασδήποτε μεταγενέστερης έκδοσής αυτής από το Ίδρυμα Ελεύθερου Λογισμικού (FSF), χωρίς αμετάβλητα τμήματα, κείμενα εξωφύλλου και κείμενα οπισθοφύλλου. Συμπεριλαμβάνεται αντίγραφο της άδειας. Πολλές από τις ονομασίες που χρησιμοποιούνται από εταιρείες για την διαφοροποίηση των προϊόντων και υπηρεσιών τους έχουν καταχωρισθεί ως εμπορικά σήματα. Σε όποιο σημείο της τεκμηρίωσης GNOME τυχόν εμφανίζονται αυτές οι ονομασίες, και εφόσον τα μέλη του Έργου τεκμηρίωσης GNOME έχουν λάβει γνώση αυτών των εμπορικών σημάτων, οι ονομασίες ή τα αρχικά αυτών θα γράφονται με κεφαλαίους χαρακτήρες. 1.33.0 1 Oct 2020 mc gtk4 version 1.32.1 15 Aug 2019 ss dev version 1.32 15 Aug 2019 ss hotfix release 1.31 05 Aug 2019 ss refactorings and more test coverage 1.30 08 May 2019 ss more test coverage 1.29 28 Aug 2018 ss bug fixes 1.28 24 Mar 2018 ss bug fixes 1.27 07 Dec 2017 ss fine tuning of the python port 1.26 11 Aug 2017 ss port all tools from perl/bash to python 1.25 21 Μαρτίου 2016 ss διορθώσεις σφαλμάτων, εκαθάρριση δοκιμαστικού κώδικα 1.24 29 Μαΐου 2015 ss διόρθωση σφαλμάτων 1.23 17 Μαΐου 2015 ss διόρθωση σφαλμάτων 1.22 07 Μαΐου 2015 ss διορθώσεις σφαλμάτων, απόρριψη παρωχημένων λειτουργιών 1.21 17 Ιουλ 2013 ss διορθώσεις σφαλμάτων, απόρριψη παρωχημένων λειτουργιών 1.20 16 Φεβ 2014 ss διορθώσεις σφαλμάτων, υποστήριξη markdown, και βελτιώσεις στυλ 1.19 05 Ιουν 2013 ss διόρθωση σφαλμάτων 1.18 14 Σεπτ 2011 ss διορθώσεις σφαλμάτων, επιταχύνσεις, υποστήριξη markdown 1.17 26 Φεβ 2011 sk επείγουσα διόρθωση σφάλματος 1.16 14 Ιαν 2011 sk διορθώσεις σφαλμάτων και βελτιώσεις διάταξης 1.15 21 Μαίου 2010 sk διορθώσεις σφαλμάτων και αναδρομής 1.14 28 Μαρτίου 2010 sk διορθώσεις σφαλμάτων και βελτιώσεις επίδοσης 1.13 18 Δεκεμβρίου 2009 sk ανανέωση κατεστραμμένου συμπιεσμένου αρχείου 1.12 18 Δεκεμβρίου 2009 sk νέα χαρακτηριστικά εργαλείων και διορθώσεις σφαλμάτων 1.11 16 Νοεμβρίου 2008 mal Μετάβαση σε GNOME doc-utils Ελληνική μεταφραστική ομάδα GNOME team@gnome.gr 2009-2016 Ελληνική μεταφραστική ομάδα GNOME Τζένη Πετούμενου epetoumenou@gmail.com 2009 Τζένη Πετούμενου Θάνος Τρυφωνίδης tomtryf@gnome.org 2012 2015 2016 Θάνος Τρυφωνίδης Δημήτρης Σπίγγος dmtrs32@gmail.com 2013-2015 Δημήτρης Σπίγγος Μαρία Θουκυδίδου marablack3@gmail.com 2014 Μαρία Θουκυδίδου Μαρία Μαυρίδου mavridou@gmail.com 2014 Μαρία Μαυρίδου Εισαγωγή Αυτό το κεφάλαιο αποτελεί μια εισαγωγή στο GTK-Doc. Περιγράφει το GTK-Doc και τον τρόπο χρήσης του. Τι είναι το GTK-Doc; GTK-Doc is used to document C code. It is typically used to document the public API of libraries, such as GLib-based libraries, but it can also be used to document application code. Πώς λειτουργεί το GTK-Doc; GTK-Doc works by reading specially-formatted comment blocks placed inside the source files to document symbols such as functions, macros, structs, enums, etc. (though note that for most kind of symbols GTK-Doc will only document the symbols that are declared in header files; for example it won't produce output for static functions). GTK-Doc also reads template files where documentation can be added there as well. GTK-Doc consists of a number of programs, each performing a different step in the process. The main steps are: Writing the documentation. The author fills in the source files with the documentation for each function, macro, structs or unions, etc. Συλλέγοντας πληροφορίες για τον κώδικα. Το gtkdoc-scan σαρώνει τα αρχεία κεφαλίδων του κώδικα ψάχνοντας για δηλώσεις συναρτήσεων, μακροεντολές, enums, δομές και ενώσεις. Δημιουργεί το αρχείο <module>-decl-list.txt που περιέχει μια λίστα με τις δηλώσεις, και τις τοποθετεί σε ενότητες αναλόγως με το αρχείο κεφαλίδας στο οποίο βρίσκονται. Από την πρώτη εκτέλεση του προγράμματος το αρχείο αντιγράφεται στο <module>-sections.txt. Ο συγγραφέας μπορεί να τακτοποιεί τις ενότητες και τη σειρά των δηλώσεων, για να παραγάγει το επιθυμητό τελικό αποτέλεσμα. Το δεύτερο αρχείο δημιουργεί το <module>-decl.txt. Το αρχείο αυτό περιέχει τις πλήρεις δηλώσεις που βρέθηκαν από τον σαρωτή.Αν για κάποιο λόγο θέλετε μερικά σύμβολα να εμφανίζονται στην τεκμηρίωση, όπου η πλήρης δήλωση δεν μπορεί να βρεθεί από τον σαρωτή, ή πρέπει να εμφανίζεται διαφορετικά, μπορεί κάποιος να τοποθετήσει οντότητες παρόμοιες με αυτές <module>-decl.txt στο αρχείο <module>-overrides.txt. Το gtkdoc-scanobj μπορεί επίσης να χρησιμοποιηθεί για να κάνει δυναμική αναζήτηση σε μια βιβλιοθήκη για ενδεχόμενες υποκλάσεις GObject. Αποθηκεύει τις πληροφορίες για τη θέση κάθε αντικειμένου στην ιεραρχία κλάσεων καθώς και για τις ιδιότητες και σήματα GObject που περιέχει. gtkdoc-scanobj should not be used anymore. It was needed in the past when GObject was still GtkObject inside GTK. Generating the XML and HTML/PDF. gtkdoc-mkdb turns the template files into XML files in the xml/ subdirectory. If the source code contains documentation for symbols, using the special comment blocks, it gets merged in here. If there are no tmpl files used it only reads docs from sources and introspection data. Το gtkdoc-mkhtml μετατρέπει τα αρχεία XML σε αρχεία HTML στον υποκατάλογο html/. Ομοίως, το gtkdoc-mkpdf μετατρέπει τα αρχεία XML σε ένα έγγραφο PDF που ονομάζεται <package>.pdf. Τα αρχεία στους καταλόγους xml/ και html/ αντικαθίστανται πάντα. Επομένως, δεν πρέπει να τα επεξεργάζεστε απευθείας. Fixing up cross-references between documents. After installing the HTML files, gtkdoc-fixxref can be run to fix up any cross-references between separate documents. For example, the GTK documentation contains many cross-references to types documented in the GLib manual. When creating the source tarball for distribution, gtkdoc-rebase turns all external links into web-links. When installing distributed (pregenerated) docs the same application will try to turn links back to local links (where those docs are installed). Λήψη GTK-Doc Απαιτήσεις python 2/3 - the main scripts are written in python. xsltproc - το πρόγραμμα xslt processor από τη βιβλιοθήκη libxslt xmlsoft.org/XSLT/ docbook-xsl - τα φύλλα στυλ docbook xsl sourceforge.net/projects/docbook/files/docbook-xsl Ένα από τα source-highlight, highlight ή vim - προαιρετικά - που χρησιμοποιούνται για την επισήμανση της σύνταξης στα παραδείγματα Περί GTK-Doc Historically GTK-Doc was used to generate template files from the sources code. These template files could be used by developers to enter the API documentation. This approach was rather inconvenient because it required to keep the generated files under version control. Since GTK-Doc 1.9 it became possible to place all API information into source comments, which made the template support obsolete. In version 1.26 template support has been removed. (ΠΡΟΣ ΔΙΟΡΘΩΣΗ) (authors, web pages, mailing list, license, future plans, comparison with other similar systems.) Περί του εγχειριδίου (ΠΡΟΣ ΔΙΟΡΘΩΣΗ) (σε ποιους απευθύνεται, πού θα το βρείτε, άδεια) Project Setup This Chapter describes the steps that are necessary to integrate GTK-Doc into your project. The integration of GTK-Doc into a project includes the following steps: Preparation of the directory structure and creating required configuration files for your GTK-Doc documentation (see Setting up a skeleton documentation). Adjusting the build system to build your documentation using the GTK-Doc tools. Multiple build systems are supported, in this manual we describe how to integrate GTK-Doc with Autotools, CMake, and plain Makefiles. Adding GTK-Doc specific files to version control and deciding which files to ignore (see Integration with version control systems). The following sections assume we work on a project called meep. This project contains two packages (or modules), a library called libmeep and an end-user app called meeper. Δημιουργία του σκελετού τεκμηρίωσης A common convention is to place documentation into a folder called docs inside your top-level project directory. We usually distinguish between reference documentation intended for developers and an user manual intended for end-users. Again the convention is to have separate folders for both. We usually place the reference documentation in a folder named reference and the end-user manual in a folder named help as. According to the above convention the documentation for our libmeep package would be placed into: docs/reference/libmeep. For packages with just one library or application the documentation could also be placed directly into docs/reference. It is not mandatory to use the above convention, but if you choose to use a different directory structure you must adjust your build system configuration to match your directory structure. In the following sections we will assume a directory structure for our meep project that uses the above conventions. Example directory structure of <emphasis>meep</emphasis> project Integration with Autotools Integration of GTK-Doc into an autotools-based build system requires the following steps: Ensure that gtkdocize is run once before the configure script. If an autogen.sh script is present, adjust it to check for GTK-Doc and add a call to gtkdocize. The main purpose of gtkdocize is to make the gtk-doc.make Makefile and the gtk-doc.m4 macro definition file available to the build system, either by copying or linking it into the project. Add the necessary autoconf macros to configure.ac to enable GTK-Doc in your build system to allow configuration of GTK-Doc via the generated configure script. Among others with registers the --enable-gtk-doc option with the configure script. Create an automake script for each application or library in your project. In the example used in this documentation this step applies to both meeper and libmeep. In the following sections, we will perform the above steps in reverse order. We start with the automake scripts and work our way up to configure.ac and autogen.sh. Then we show how enable Gtk-Doc in the build system and how to build the documentation. Ενσωμάτωση στο automake First copy the Makefile.am from the examples sub-directory of the gtkdoc-sources to your project's reference documentation directory (e.g. docs/reference/<package>). A local copy should be available under e.g. /usr/share/doc/gtk-doc-tools/examples/Makefile.am. If you have multiple packages repeat this for each one. Do not forget to add each Makefile.am to the AC_CONFIG_FILES macro in configure.ac. For docs/reference/libmeep/Makefile.am you will need to add the entry docs/reference/libmeep/Makefile to AC_CONFIG_FILES. Example directory structure with <filename>Makefiles.am</filename> meep/ docs/ reference/ # reference documentation libmeep/ Makefile.am meeper/ Makefile.am help/ # optional: user manual meeper/ src/ libmeep/ meeper/ Next, you need to customize the copied Makefiles and provide values for the various parameters in each Makefile.am. All settings have a comment above them that describes their purpose and how to customize the setting. Most settings are used to supply extra flags to the respective tools to which they apply. Every tool has a variable of the form (e.g. the tool gtkdoc-mkhtml has an option named MKHTML_OPTIONS). All the tools support to list the supported options. The following list explains the most relevant options. Check the example Makefile.am for additional options. is used to provide the name of the package that is being documentated (e.g. meeper, or libmeep). is used to specify the location of source directory which GTK-Doc searches for your API documentation. This will usually be DOC_SOURCE_DIR=$(top_srcdir)/src or a sub-directory of that directory. and are used for dependencies. Each option take a file-glob (e.g. HFILE_GLOB=$(top_srcdir)/src/*.c). The documentation will be rebuilt if any of the matched files change. allows to specify extra header files to include when scanning for API documentation, which are not found under DOC_SOURCE_DIR (e.g. EXTRA_HFILES=$(top_srcdir}/contrib/extra.h). allows to specify header files or directories to ignore when scanning for API documentation. Use the basename of the file or directory (e.g. IGNORE_HFILES=gtkdebug.h gtkintl.h private_code_folder). allows to specify images files which will be copied into the html/ directory of the generated documentation. If your API documentation includes any images they need to be added to this option (e.g. HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png). allows to specify extra files that are included by $(DOC_MAIN_SGML_FILE) (e.g. content_files=running.xml building.xml changes-2.0.xml). allows to specify files where gtk-doc abbreviations such as #GtkWidget are expanded (e.g. expand_content_files=running.xml). Ενσωμάτωση στο autoconf Integration with autoconf is very simple and includes one required step and an additional optional (but recommended) step. The first step is to add the GTK_DOC_CHECK macro to your configure.ac script. This registers several configure options to enable GTK-Doc and allows you to set default arguments for gtkdocize. Make sure that the GTK_DOC_CHECK macro is not indented. The macro must start at the beginning of the line and should not start with whitespace. The second step is to add the AC_CONFIG_MACRO_DIR(m4) to your configure.ac. This is not required but helps gtkdocize to automatically copy the macro definition (e.g gtk-doc.m4) which contains the GTK_DOC_CHECK macro to your project's macro directory. Without this, the GTK_DOC_CHECK macro might not be found and you would need to explicitly tell the aclocal tool where to find the macro definition file. Minimal integration with autoconf The above example works, but will require all developers to have gtk-doc installed. A better way is to make building the documentation optional as shown in the next example: Integration with optional gtk-doc dependency The first argument is used to check for the Gtk-Doc version at configure time. The 2nd, optional argument is used by gtkdocize. The GTK_DOC_CHECK macro also adds several configure switches: --with-html-dir= PATH : διαδρομή προς την εγκατεστημένη τεκμηρίωση --enable-gtk-doc : χρήση gtk-doc για τη δόμηση τεκμηρίωσης [προεπιλογή=no] --enable-gtk-doc-html : δόμηση τεκμηρίωσης σε μορφή html [προεπιλογή=yes] --enable-gtk-doc-pdf : δόμηση τεκμηρίωσης σε μορφή pdf [προεπιλογή=no] Το GTK-Doc είναι απενεργοποιημένο από προεπιλογή! Να θυμάστε να χρησιμοποιείτε την επιλογή στην επόμενη εκτέλεση του configure. Διαφορετικά, εγκαθίσταται η προπαραχθείσα τεκμηρίωση (δυνατότητα χρήσιμη για τον χρήστη, αλλά όχι για τον προγραμματιστή). After all changes to configure.ac are made, update the configure file. This can be done by re-running autogen.sh. Ενσωμάτωση στο autogen Most projects will have an autogen.sh script to setup the build infrastructure after the project was checked out from a version control system (such as git or svn). GTK-Doc comes with a script called gtkdocize which can be used to copy the necessary files needed by Gtk-Doc to the source directory. It should be run before autoreconf, autoheader, automake or autoconf. Εκτέλεση του gtkdocize από το autogen.sh gtkdocize || exit 1 Conditionally run gtkdocize from autogen.sh /dev/null) if test $? -ne 0; then echo "No gtk-doc support found. You can't build the docs." else $GTKDOCIZE || exit 1 fi ]]> When running gtkdocize it copies gtk-doc.make to your project root (or any directory specified by the option). gtkdocize checks your configure.ac script for the GTK_DOC_CHECK macro. The GTK_DOC_CHECK macro can be used to pass extra arguments to the gtkdocize script. the 2nd parameter in the GTK_DOC_CHECK macro. Alternatively, additional arguments can also be passed to gtkdocize via the GTKDOCIZE_FLAGS environment variable, or by directly specifying them to gtkdocize in autogen.sh. Executing GTK-Doc from the Build System Αφού ολοκληρωθούν τα προηγούμενα βήματα, προχωρήστε στην δόμηση. Πρώτα, θα πρέπει να εκτελεσθεί εκ νέου το autogen.sh. Αν το σενάριο εκτελεί και το configure, προσθέστε την επιλογή . Διαφορετικά, εκτελέστε εσείς τοconfigure με αυτή την επιλογή. Η πρώτη εκτέλεση του make δημιουργεί μια σειρά από πρόσθετα αρχεία στους καταλόγους της τεκμηρίωσης. Τα σημαντικά είναι τα: <package>.types, <package>-docs.xml (στο παρελθόν .sgml), <package>-sections.txt. Εκτέλεση της δόμησης τεκμηρίωσης ./autogen.sh --enable-gtk-doc make Now you can point your browser to docs/reference/<package>/index.html. With this initial setup you will only see a very simple document. The next chapter will teach you how to add API documentation to your code via special comment blocks. The Chapter afterwards introduces additional files and shows how to edit the master template to add additional chapters and sections to your documentation files. Ενσωμάτωση με συστήματα δόμησης CMake Το GTK-Doc παρέχει το άρθρωμα GtkDocConfig.cmake (και το αντίστοιχο άρθρωμα GtkDocConfigVersion.cmake). Επίσης παρέχει την εντολή gtk_doc_add_module την οποία μπορείτε να ορίσετε στο αρχείο CMakeLists.txt. Το ακόλουθο παράδειγμα δείχνει πως να χρησιμοποιήσετε την εντολή. Παράδειγμα χρήσης του GTK-Doc από το CMake find_package(GtkDoc 1.25 REQUIRED) # Create the doc-libmeep target. gtk_doc_add_module( libmeep ${CMAKE_SOURCE_DIR}/libmeep XML meep-docs.xml LIBRARIES libmeep ) # Build doc-libmeep as part of the default target. Without this, you would # have to explicitly run something like `make doc-libmeep` to build the docs. add_custom_target(documentation ALL DEPENDS doc-libmeep) # Install the docs. (This assumes you're using the GNUInstallDirs CMake module # to set the CMAKE_INSTALL_DOCDIR variable correctly). install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html DESTINATION ${CMAKE_INSTALL_DOCDIR}) Ενσωμάτωση στα αρχεία makefiles ή άλλα συστήματα δόμησης Στην περίπτωση που κάποιος δε θέλει να χρησιμοποιήσει το automake και, επομένως, το gtk-doc.mak θα χρειαστεί να καλέσει τα εργαλεία του gtkdoc στη σωστή σειρά στα makefiles (ή άλλα εργαλεία δόμησης). Βήματα δόμησης τεκμηρίωσης DOC_MODULE=meep // sources have changed gtkdoc-scan --module=$(DOC_MODULE) --source-dir=... gtkdoc-scangobj --module=$(DOC_MODULE) gtkdoc-mkdb --module=$(DOC_MODULE) --output-format=xml // xml files have changed mkdir html cd html && gtkdoc-mkhtml $(DOC_MODULE) ../meep-docs.xml gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html Πρέπει να κοιτάξετε στα αρχεία Makefile.am και gtk-doc.mak για να επιλέξετε τις ρυθμίσεις που χρειάζονται. Ενσωμάτωση σε συστήματα ελέγχου εκδόσεων Ο εμπειρικός κανόνας είναι ότι αυτά τα αρχεία που επεξεργασθήκατε πρέπει να περάσουν από τον έλεγχο έκδοσης. Για τυπικά έργα, πρόκειται για τα αρχεία: <package>.types, <package>-docs.xml (στο παρελθόν .sgml), <package>-sections.txt, Makefile.am. Αρχεία στους καταλόγους xml/ και html/ δεν θα πρέπει να υποβληθούν σε έλεγχο έκδοσης. Ούτε και αρχεία xml/ and html/. Τεκμηρίωση κώδικα Το GTK-Doc χρησιμοποιεί σχόλια με ειδική σύνταξη για την προσθήκη τεκμηρίωσης στον κώδικα. Παράλληλα, ανακαλεί πληροφορίες για τη δομή του έργου σας από άλλες πηγές. Στην επόμενη ενότητα περιέχονται όλες οι λεπτομέρειες για τη σύνταξη αυτών των σχολίων. The GTK-Doc scanner can handle the majority of C headers fine. In the case of receiving warnings from the scanner that look like a special case, one can hint GTK-Doc to skip over them. GTK-Doc comment block Περιορισμοί Σημειώστε, ότι το GTK-Doc υποστηρίζει το #ifndef(__GTK_DOC_IGNORE__), αλλά όχι το #if !defined(__GTK_DOC_IGNORE__) ή άλλους συνδυασμούς. Σχόλια τεκμηρίωσης Ένα σχόλιο πολλαπλών γραμμών που διαθέτει ένα επιπλέον «*» στην αρχή αποτελεί ένα μπλοκ τεκμηρίωσης που λαμβάνεται υπόψη από τα εργαλεία του GTK-Doc. Μπλοκ σχολίου GTK-Doc /** * identifier: * documentation ... */ Το 'αναγνωριστικό' είναι μία γραμμή που περιέχει το όνομα του στοιχείου στο οποίο αναφέρεται το σχόλιο. Η σύνταξή του εξαρτάται από τον τύπο του στοιχείου. (ΜΕΛΛΟΝΤΙΚΑ: να προστεθεί πίνακας με τα αναγνωριστικά) Η ομάδα 'τεκμηρίωσης' επίσης διαφέρει ανάλογα με τον τύπο συμβόλου. Για τους τύπους συμβόλων που δέχονται παραμέτρους όπως συναρτήσεις ή μακροεντολές προηγείται η περιγραφή των παραμέτρων και ακολουθεί μια κενή γραμμή (μόνο '*'). Ακολουθεί η λεπτομερής περιγραφή. Όλες οι γραμμές (εκτός από τις λίστες προγράμματος και τις ενότητες CDATA) που περιέχουν μόνο ένα ' *' (διάστημα-αστερίσκο) μετατρέπονται σε αλλαγές παραγράφου. Αν δεν επιθυμείτε αλλαγή παραγράφου, αλλάξτε το σε ' * ' (διάστημα-αστερίσκος-διάστημα-διάστημα). Αυτό είναι χρήσιμο σε προδιαμορφωμένο κείμενο (λίστες κώδικα). Όταν τεκμηριώνετε κώδικα, περιγράψτε δύο πλευρές: Τι είναι: Το όνομα της κλάσης ή της συνάρτησης μπορεί μερικές φορές να είναι παραπλανητικό για ανθρώπους που δεν έχουν τεχνογνωσία στο θέμα. Τι κάνει: Αναφέρει τις κοινές χρήσεις και τις βάζει σε σχέση με άλλο API. Ένα πλεονέκτημα της χρήσης υπερκειμένου αντί για απλό κείμενο, είναι η δυνατότητα προσθήκης συνδέσμων στο έγγραφο. Ωστόσο, η συγγραφή της σωστής επισήμανσης για έναν σύνδεσμο μπορεί να είναι αρκετά κουραστική διαδικασία. Το GTK-Doc σας βοηθάει, παρέχοντάς σας μια σειρά από χρήσιμες συντομεύσεις. Χρησιμοποιήστε το function() για να αναφερθείτε σε συναρτήσεις ή μακροεντολές που δέχονται ορίσματα. Χρησιμοποιήστε το @param για να αναφερθείτε σε παραμέτρους. Επίσης, χρησιμοποιήστε αυτή τη γραφή για να αναφερθείτε σε παραμέτρους άλλων συναρτήσεων, σχετικών με την περιγραφόμενη. Χρησιμοποιήστε το %constant για να αναφερθείτε σε σταθερές, π.χ. %G_TRAVERSE_LEAFS. Χρησιμοποιήστε το #symbol για να αναφερθείτε σε άλλους τύπους συμβόλων, π.χ. δομές, αριθμήσεις και μακροεντολές που δε δέχονται ορίσματα. Χρησιμοποιήστε το #Object::signal για να αναφερθείτε σε ένα σήμα GObject. Χρησιμοποιήστε το #Object::property για να αναφερθείτε σε μία ιδιότητα GObject. Χρησιμοποιήστε το #Struct.field για να αναφερθείτε σε ένα πεδίο μέσα σε μια δομή και #GObjectClass.foo_bar() για να αναφερθείτε σε μια vmethod. Αν θέλετε να χρησιμοποιήσετε τους ειδικούς χαρακτήρες «<», «>», «()», «@», «%» ή «#» στην τεκμηρίωση, χωρίς να φοβάστε ότι θα τους αλλάξει το GTK-Doc, μπορείτε να χρησιμοποιήσετε τις οντότητες XML «&lt;», «&gt;», «&lpar;», «&rpar;», «&commat;», «&percnt;» και «&num;», αντίστοιχα, ή να χρησιμοποιήσετε την ανάποδη κάθετο «\» ως χαρακτήρα διαφυγής. Το DocBook μπορεί να κάνει παραπάνω από απλούς συνδέσμους. Μπορεί κάποιος να έχει και λίστες, παραδείγματα, κεφαλίδες και εικόνες. Από την έκδοση 1.20 και μετά, ο προτιμώμενος τρόπος είναι με τη χρήση ενός υποσυνόλου της βασικής σύνταξης για μορφοποίηση κειμένου που ονομάζεται Markdown. Σε παλιότερες εκδόσεις GTK-Doc οποιαδήποτε τεκμηρίωση που περιλαμβάνει Markdown θα αποδίδεται ως έχει. Για παράδειγμα, οι καταχωρήσεις της λίστας θα εμφανίζονται σαν γραμμές που αρχίζουν με μια παύλα. Αν και τώρα προτιμάται η Markdown μπορεί κάποιος να αναμείξει και τις δύο. Ένας περιορισμός εδώ είναι ότι κάποιος μπορεί να χρησιμοποιήσει το docbook xml μέσα στο markdown, αλλά το markdown μέσα στο docbook xml δεν υποστηρίζεται. Σε παλιότερες εκδόσεις του GTK-Doc, αν χρειάζεστε υποστήριξη για πρόσθετη μορφοποίηση, θα πρέπει να ενεργοποιήσετε τη χρήση των ετικετών docbook XML μέσα στα doc-comments θέτοντας το (ή το ) στη μεταβλητή MKDB_OPTIONS μέσα στο Makefile.am. Μπλοκ σχολίου GTK-Doc χρησιμοποιώντας Markdown /** * ταυτοποιητής: * * παράγραφος τεκμηρίωσης ... * * # Δευτερεύουσα επικεφαλίδα # * * ## Δεύτερη δευτερεύουσα επικεφαλίδα * * # Δευτερεύουσα επικεφαλίδα με μια άγκυρα συνδέσμου # {#επικεφαλίδα-δύο} * * περισσότερη τεκμηρίωση: * * - στοιχείο 1 καταλόγου * * Παράγραφος μέσα σε ένα στοιχείο καταλόγου. * * - στοιχείο καταλόγου 2 * * 1. αριθμημένο στοιχείο καταλόγου * * 2. άλλο αριθμημένο στοιχείο καταλόγου * * Μια άλλη παράγραφος. [Ένας σύνδεσμος στην ιστοσελίδα GNOME](http://www.gnome.org/) * * ![μια ενσωματωμένη εικόνα ](plot-result.png) * * [Ένας σύνδεσμος στην από πάνω άγκυρα επικεφαλίδας][επικεφαλίδα-δύο] * * Ένα παράδειγμα γλώσσας C: * |[<!-- language="C" --> * GtkWidget *label = gtk_label_new ("Gorgeous!"); * ]| */ More examples of what markdown tags are supported can be found in the GTK Documentation Markdown Syntax Reference. As already mentioned earlier GTK-Doc is for documenting public API. Thus one cannot write documentation for static symbols. Nevertheless it is good to comment those symbols too. This helps other developers to understand your code. Therefore we recommend to comment these using normal comments (without the 2nd '*' in the first line). If later the function needs to be made public, all one needs to do is to add another '*' in the comment block and insert the symbol name at the right place inside the sections file. Τεκμηρίωση ενοτήτων Κάθε ενότητα της τεκμηρίωσης περιέχει πληροφορίες για μια κλάση ή ένα άρθρωμα. Για να εισάγετε το συστατικό μπορείτε να γράψετε ένα μπλοκ σχολίου ενότητας. Η σύντομη αυτή περιγραφή χρησιμοποιείται και για τον πίνακα περιεχομένων. Όλα τα πεδία @fields είναι προαιρετικά. Μπλοκ σχολίου ενότητας /** * SECTION:meepapp * @short_description: the application class * @title: Meep application * @section_id: * @see_also: #MeepSettings * @stability: Stable * @include: meep/app.h * @image: application.png * * The application class handles ... */ SECTION:<name> The name links the section documentation to the respective part in the <package>-sections.txt file. The name given here should match the <FILE> tag in the <package>-sections.txt file. @short_description Περιγραφή της ενότητας σε μια γραμμή, η οποία θα εμφανίζεται, στη συνέχεια, μετά από τους συνδέσμους του πίνακα περιεχομένων και στην αρχή της σελίδας της ενότητας. @title Ο τίτλος της ενότητας από προεπιλογή έχει όνομα <name> από τη δήλωση SECTION. Μπορεί να παρακαμφθεί με το πεδίο @title. @section_id Παρακάμπτει τη χρήση του τίτλου ως αναγνωριστικό της ενότητας. Για αντικείμενα GOBject το <title> χρησιμοποιείται ως section_id και για άλλες ενότητες είναι <MODULE>-<title>. @see_also Λίστα συμβόλων σχετικών με αυτή την ενότητα. @stability Άτυπη περιγραφή του επιπέδου σταθερότητας του συγκεκριμένου API. Σας συνιστούμε τη χρήση ενός από τους ακόλουθους όρους: Σταθερή - Μια σταθερή διεπαφή επιτρέπει σε τρίτους να αναπτύσσουν εφαρμογές για τις διεπαφές αυτές, να τις δημοσιεύουν και να είναι βέβαιοι ότι οι εφαρμογές θα τρέχουν σε όλες τις ελάσσονες εκδόσεις του προϊόντος (οι οποίες θα είναι μεταγενέστερες της διεπαφής και θα ανήκουν στην ίδια μείζονα έκδοση). Ακόμη και όταν πρόκειται για μείζονες νέες εκδόσεις, οι ασυμβατότητες αναμένεται να είναι σπάνιες και να οφείλονται σε σοβαρούς λόγους. Ασταθής - Ασταθείς είναι οι πειραματικές ή μεταβατικές διεπαφές. Συνήθως χρησιμοποιούνται για να παρέχουν σε τρίτους πρώιμη πρόσβαση σε νέες ή διαρκώς εξελισσόμενες τεχνολογίες, ή ως ενδιάμεσες λύσεις για προβλήματα για τα οποία αναμένεται μια γενικότερη λύση. Δεν υφίσταται καμία εγγύηση συμβατότητας μεταξύ μιας ελάσσονας έκδοσης και της επόμενης. Ιδιωτική - Διεπαφή που μπορεί να χρησιμοποιηθεί εντός της στοίβας του GNOME, αλλά δε διαθέτει τεκμηρίωση που να απευθύνεται στους τελικούς χρήστες. Τέτοιου είδους συναρτήσεις μπορούν να χρησιμοποιούνται μόνο στο πλαίσιο σαφώς καθορισμένων και τεκμηριωμένων διαδικασιών. Εσωτερική - Μια διεπαφή που είναι εσωτερική σε ένα άρθρωμα και δεν απαιτεί την ύπαρξη τεκμηρίωσης για τον τελικό χρήστη. Οι συναρτήσεις που δεν περιέχουν τεκμηρίωση εκλαμβάνονται ως εσωτερικές. @include Αρχεία #include που εμφανίζονται στη συνοπτική παρουσίαση των ενοτήτων (λίστα αρχείων που χωρίζονται με κόμματα), αντικαθιστώντας την καθολική τιμή στο αρχείο ενότητας ή στη γραμμή εντολών. Πρόκειται για προαιρετικό στοιχείο. @image Η εικόνα που θα εμφανίζεται στο πάνω μέρος της σελίδας αναφοράς για αυτή την ενότητα. Αυτή συχνά θα είναι κάποιου είδους διάγραμμα για την απεικόνιση μια κλάσης ή ενός διαγράμματος της σχέσης της με άλλες κλάσεις. Αυτή η καταχώρηση είναι προαιρετική. Για να μη χρειαστεί να κάνετε εκ νέου μεταγλώττιση μετά από αλλαγές στην τεκμηρίωση, σας προτείνουμε να ενσωματώνετε την τεκμηρίωση των ενοτήτων στο αρχείο του πηγαίου κώδικα, όπου αυτό είναι δυνατό. Τεκμηρίωση συμβόλων Κάθε σύμβολο (συνάρτηση, μακροεντολή, δομή, αρίθμηση, σήμα, ιδιότητα) τεκμηριώνεται σε ξεχωριστή ομάδα. Η καταλληλότερη θέση για τις ομάδες είναι δίπλα στους ορισμούς των συμβόλων, γιατί διευκολύνει το έργο συγχρονισμού. Επομένως, η τεκμηρίωση των συναρτήσεων συνήθως βρίσκεται στο αρχείο του πηγαίου κώδικα, ενώ των μακροεντολών, δομών και αριθμήσεων στο αρχείο κεφαλίδας. Γενικές ετικέτες Μπορείτε να προσθέσετε πληροφορίες εκδόσεων σε όλα τα στοιχεία της τεκμηρίωσης για να πείτε πότε εισήχθηκε ένα API, ή πότε καταργήθηκε. Εκδόσεις Ετικετών Από: Περιγραφή οπό ποια έκδοση του κώδικα και μετά είναι διαθέσιμο το API. Παρωχημένη: Παράγραφος που επισημαίνει ότι θα πρέπει να σταματήσει η χρήση της συνάρτησης. Η περιγραφή θα πρέπει να παραπέμπει τον αναγνώστη στο νέο API. Μπορείτε επίσης να προσθέσετε πληροφορίες σταθερότητας σε όλα τα στοιχεία της τεκμηρίωσης για να δείξετε αν η σταθερότητα API είναι εγγυημένη για αυτά για όλες τις μελλοντικές δευτερεύουσες εκδόσεις του έργου. Το επίπεδο προεπιλεγμένης σταθερότητας για όλα τα στοιχεία τεκμηρίωσης μπορούν να οριστούν μεταφέροντας το όρισμα στην gtkdoc-mkdb με μια άπω τις παρακάτω τιμές. Ετικέτες σταθερότητας Σταθερότητα: σταθερό Σημείωση του στοιχείου ως σταθερού. Αυτό είναι για δημόσια APIs που είναι βέβαια ότι παραμένουν σταθερά για όλες τις μελλοντικές δευτερεύουσες εκδόσεις του έργου. Σταθερότητα: ασταθές Σημείωση του στοιχείου ως ασταθούς. Αυτό είναι για τα δημόσια APIs που εκδίδονται ως μια προεπισκόπηση πριν να σταθεροποιηθούν. Σταθερότητα: προσωπική Σημείωση του στοιχείου ως προσωπικό. Αυτό είναι για διεπαφές που μπορούν να χρησιμοποιηθούν με σφικτά συνδυασμένες ενότητες, αλλά όχι από ελεύθερα τρίτα μέρη. Γενικές ετικέτες /** * foo_get_bar: * @foo: some foo * * Retrieves @foo's bar. * * Returns: @foo's bar * * Since: 2.6 * Deprecated: 2.12: Use foo_baz_get_bar() instead. */ Bar * foo_get_bar(Foo *foo) { ... Σχόλια Documentation blocks can contain annotation-tags. These tags will be rendered with tooltips describing their meaning. The tags are used by GObject Introspection to generate language bindings. A detailed list of the supported tags can be found in the GObject Introspection documentation. Σχόλια /** * foo_get_bar: (σχόλιο) * @foo: (σχόλιο): some foo * * Ανακτά @foo's bar. * * Επιστρέφει: (σχόλιο): @foo's bar */ ... /** * foo_set_bar_using_the_frobnicator: (σχόλιο) (ένα άλλο σχόλιο) * (και ένα άλλο σχόλιο) * @foo: (σχόλιο) (ένα άλλο σχόλιο): some foo * * Ορίζει γραμμή στο @foo. */ Ομάδα σχολίων συνάρτησης Παρακαλούμε να θυμηθείτε να: Τεκμηριώστε κατά πόσο τα επιστρεφόμενα αντικείμενα, λίστες, συμβολοσειρές, κ.λπ, θα πρέπει να ελευθερώνονται, να μην ελευθερώνονται ή να απορρίπτονται. Τεκμηριώσετε κατά πόσο οι παράμετροι μπορούν να είναι μηδενικές (NULL) και τι συμβαίνει αν είναι. Αναφέρετε ενδιαφέρουσες προ-καταστάσεις και μετα-καταστάσεις όπου χρειάζεται. Το Gtk-doc θεωρεί ότι όλα τα σύμβολα (μακροεντολές, συναρτήσεις, κτλ.) που ξεκινούν με '_' είναι ιδιωτικά και τα μεταχειρίζεται σαν στατικές συναρτήσεις. Ομάδα σχολίων συνάρτησης /** * function_name: * @par1: description of parameter 1. These can extend over more than * one line. * @par2: description of parameter 2 * @...: a %NULL-terminated list of bars * * The function description goes here. You can use @par1 to refer to parameters * so that they are highlighted in the output. You can also use %constant * for constants, function_name2() for functions and #GtkWidget for links to * other declarations (which may be documented elsewhere). * * Returns: an integer. * * Since: 2.2 * Deprecated: 2.18: Use other_function() instead. */ Ετικέτες συναρτήσεων Επιστροφές: Παράγραφος που περιγράφει το επιστρεφόμενο αποτέλεσμα. @...: Σε περίπτωση που η συνάρτηση μπορεί να δεχθεί μεταβλητό αριθμό ορισμάτων (variadic), πρέπει να χρησιμοποιήσετε αυτή την ετικέτα (η ετικέτα @Varargs: λειτουργεί επίσης, για ιστορικούς λόγους). Ομάδα σχολίων ιδιότητας Ομάδα σχολίων ιδιότητας /** * SomeWidget:some-property: * * Here you can document a property. */ g_object_class_install_property (object_class, PROP_SOME_PROPERTY, ...); Ομάδα σχολίων σήματος Παρακαλούμε να θυμηθείτε να: Τεκμηριώστε πότε εκπέμπεται το σήμα και κατά πόσο εκπέμπεται πριν ή μετά από άλλα σήματα. Τεκμηριώστε τι μπορεί να κάνει μια εφαρμογή στον διαχειριστή σημάτων. Ομάδα σχολίων σήματος Ομάδα σχολίων δομής Ομάδα σχολίων δομής /** * FooWidget: * @bar: some #gboolean * * This is the best widget, ever. */ typedef struct _FooWidget { GtkWidget parent_instance; gboolean bar; } FooWidget; Χρησιμοποιήστε το /*< private >*/ πριν από πεδία ιδιωτικών δομών που θέλετε να αποκρύψετε. Χρησιμοποιήστε το /*< public >*/για την αντίστροφη συμπεριφορά. Αν το πρώτο πεδίο είναι "g_iface", "parent_instance" ή "parent_class" θα θεωρηθεί αυτόματα ιδιωτικό και δεν θα χρειαστεί να αναφερθεί στην περιοχή των σχολίων. Οι ομάδες σχολίων μιας δομής μπορούν επίσης να χρησιμοποιηθούν για GObjects και για GObjectClasses. Είναι συνήθως καλή ιδέα να προσθέτετε μία ομάδα σχολίου για μια κλάση, εάν έχει vmethods (γιατί έτσι μπορούν να τεκμηριωθούν). Για το ίδιο το GObject μπορείτε να χρησιμοποιήσετε τα σχετικά έγγραφα τμημάτων, έχοντας μία ξεχωριστή ομάδα για το στιγμιότυπο δομής θα ήταν χρήσιμο εάν το στιγμιότυπο έχει δημόσια πεδία. Ένα μειονέκτημα εδώ είναι ότι θα δημιουργηθούν δύο καταχωρήσεις δεικτών για το ίδιο όνομα (για την δομή και για το τμήμα). Ομάδα σχολίων Enum Ομάδα σχολίων Enum /** * Something: * @SOMETHING_FOO: something foo * @SOMETHING_BAR: something bar * * Enum values used for the thing, to specify the thing. */ typedef enum { SOMETHING_FOO, SOMETHING_BAR, /*< private >*/ SOMETHING_COUNT } Something; Χρησιμοποιήστε το /*< private >*/ πριν από ιδιωτικές τιμές enum που θέλετε να αποκρύψετε. Χρησιμοποιήστε το /*< public >*/ για την αντίστροφη συμπεριφορά. Inline program documentation You can document programs and their commandline interface using inline documentation. Tags PROGRAM Defines the start of a program documentation. @short_description: Defines a short description of the program. (Optional) @synopsis: Defines the arguments, or list of arguments that the program can take. (Optional) @see_also: See Also manual page section. (Optional) @arg: Argument(s) passed to the program and their description. (Optional) Description: A longer description of the program. Επιστροφές: Specify what value(s) the program returns. (Optional) Example of program documentation. Program documentation block Χρήσιμες ετικέτες DocBook Ακολουθούν ορισμένες ετικέτες DocBook, ιδιαίτερα χρήσιμες για την τεκμηρίωση του κώδικα. Για να συνδεθείτε με μια άλλη ενότητα στην τεκμηρίωση GTK: <link linkend="glib-Hash-Tables">Hash Tables</link> Ο προορισμός είναι το αναγνωριστικό του SGML/XML στο πρώτο στοιχείο της σελίδας στην οποία παραπέμπει ο σύνδεσμος. Για τις περισσότερες σελίδες είναι το ("gtk", "gdk", glib"), ακολουθούμενο από τον τίτλο της σελίδας ("Πίνακες Hash"). Για τα γραφικά συστατικά είναι το όνομα της κλάσης. Τα διαστήματα και τα «_» μετατρέπονται σε «-» για να υπάρχει συμμόρφωση με το SGML/XML. Αναφορά σε εξωτερική συνάρτηση, π.χ. τυποποιημένη συνάρτηση C: <function>...</function> To include example code: Using a GHashTable. ... ]]> or possibly this, for very short code fragments which don't need a title: ... ]]> In both cases, the language attribute is optional and is used as a hint to the syntax highlighting engine (pygments for html output). For the latter GTK-Doc also supports an abbreviation: ... ]| ]]> Συμπερίληψη λιστών με κουκκίδες: <itemizedlist> <listitem> <para> ... </para> </listitem> <listitem> <para> ... </para> </listitem> </itemizedlist> Συμπερίληψη σημειώσεων που ξεχωρίζουν από το υπόλοιπο κείμενο: <note> <para> Make sure you free the data after use. </para> </note> Για να αναφερθείτε σε έναν τύπο: <type>unsigned char</type> Για να αναφερθείτε σε μια εξωτερική δομή (που δεν περιγράφεται στην τεκμηρίωση GTK): <structname>XFontStruct</structname> Για να αναφερθείτε σε ένα πεδίο μιας δομής: <structfield>len</structfield> Για να αναφερθείτε σε ένα όνομα κλάσης, θα μπορούσατε να χρησιμοποιήσετε το : <classname>GtkWidget</classname> , αλλά μάλλον θα χρησιμοποιήσετε το #GtkWidget (για αυτόματη δημιουργία συνδέσμου προς τη σελίδα GtkWidget, δείτε τις συντομεύσεις). Χρήση έντονων χαρακτήρων: <emphasis>This is important</emphasis> Για ονόματα αρχείων χρησιμοποιήστε: <filename>/home/user/documents</filename> Για να αναφερθείτε σε κλειδιά χρησιμοποιήστε: <keycombo><keycap>Control</keycap><keycap>L</keycap></keycombo> Συμπλήρωση των επιπλέον αρχείων Υπάρχουν ορισμένα επιπλέον αρχεία που πρέπει να ενημερώνονται παράλληλα με τα σχόλια εντός του πηγαίου κώδικα: <package>.types, <package>-docs.xml (στο παρελθόν .sgml), <package>-sections.txt. Επεξεργασία του αρχείου types Αν η βιβλιοθήκη ή η εφαρμογή σας περιέχει GObjects, θα θέλετε να εμφανίζονται στην τεκμηρίωση τα σήματα, τα ορίσματα/παράμετροι καθώς και η θέση τους στην ιεραρχία. Για να το πετύχετε, απλά καταγράψτε τις συναρτήσεις xxx_get_type μαζί με την συμπερίληψή τους στο αρχείο <package>.types. Example <package>.types file #include <gtk/gtk.h> gtk_accel_label_get_type gtk_adjustment_get_type gtk_alignment_get_type gtk_arrow_get_type Από την έκδοση 1.8 και μετά το gtkdoc-scan μπορεί να παράγει αυτόματα αυτή τη λίστα. Απλά προσθέστε την επιλογή "--rebuild-types" στο SCAN_OPTIONS του Makefile.am. Αν προτιμήσετε αυτή την προσέγγιση, θα πρέπει να μη συμπεριλάβετε το αρχείο types ούτε στη διανομή ούτε στον έλεγχο εκδόσεων. Επεξεργασία κύριου εγγράφου (master) Το GTK-Doc παράγει τεκμηρίωση σε μορφή SGML/XML DocBook. Κατά την επεξεργασία των σχολίων εντός του πηγαίου κώδικα, τα εργαλεία του GTK-Doc παράγουν μία σελίδα τεκμηρίωσης ανά κλάση ή άρθρωμα, η οποία αποθηκεύεται ως ξεχωριστό αρχείο. Το κύριο έγγραφο συμπεριλαμβάνει αυτά τα αρχεία και τα ταξινομεί. Αν και το GTK-Doc παράγει αυτόματα ένα πρότυπο κύριο έγγραφο για σας, οι επόμενες εκτελέσεις δεν θα το ξαναθίξουν. Αυτό σημαίνει ότι μπορείτε να δομήσετε την τεκμηρίωση ελεύθερα. Αυτό περιλαμβάνει την ομαδοποίηση των σελίδων και την προσθήκη πρόσθετων σελίδων. Το GTK-Doc διαθέτει πλέον μια σουίτα για δοκιμές, στην οποία το κύριο έγγραφο αναδημιουργείται από την αρχή. Είναι καλό να το κοιτάτε κάπου-κάπου για να δείτε αν υπάρχουν κάποια νέα καλούδια που εισήχθησαν εκεί. Μη δημιουργείτε εγχειρίδια ως νέα έγγραφα. Απλά προσθέστε επιπλέον κεφάλαια. Το όφελος της ενσωμάτωσης απευθείας του εγχειριδίου για μια βιβλιοθήκη στην τεκμηρίωση API είναι ότι έτσι διευκολύνεται η διαδικασία δημιουργίας συνδέσμων από το εγχειρίδιο προς την τεκμηρίωση των συμβόλων. Επίσης, έτσι καθίσταται πιθανότερη η ενημέρωση του εγχειριδίου μαζί με τη βιβλιοθήκη. Ποιες είναι λοιπόν οι αλλαγές που πρέπει να γίνουν στο κύριο έγγραφο; Πρόκειται για λίγες μόνο αλλαγές σε ορισμένα placeholders (κείμενα εντός αγκυλών) που πρέπει να διευκρινήσετε. Κεφαλίδα κύριου εγγράφου <bookinfo> <title>MODULENAME Reference Manual</title> <releaseinfo> for MODULENAME [VERSION] The latest version of this documentation can be found on-line at <ulink role="online-location" url="http://[SERVER]/MODULENAME/index.html">http://[SERVER]/MODULENAME/</ulink>. </releaseinfo> </bookinfo> <chapter> <title>[Insert title here]</title> Επιπλέον κάποια στοιχεία επιλογής δημιουργούνται με μορφή σχολίου. Μπορείτε να τα ελέγξετε και να τα ενεργοποιήσετε όπως θέλετε. Προαιρετικό τμήμα στο κύριο έγγραφο --> ]]> Τέλος, χρειάζεται να προσθέσετε νέα ενότητα όποτε εισάγετε μία. Το εργαλείο gtkdoc-check θα σας θυμίσει τα νεοδημιουργούμενα αρχεία xml που δεν περιλαμβάνονται ακόμα στο έγγραφο. Συμπερίληψη των δημιουργούμενων ενοτήτων <chapter> <title>my library</title> <xi:include href="xml/object.xml"/> ... Επεξεργασία αρχείου ενοτήτων Το αρχείο ενοτήτων χρησιμεύει στην οργάνωση της τεκμηρίωσης που παράγεται από το GTK-Doc. Εδώ διευκρινίζεται σε ποιο άρθρωμα ή κλάση ανήκει κάθε σύμβολο και αποφασίζεται η ορατότητά του (αν θα είναι δημόσιο ή ιδιωτικό). Το αρχείο ενοτήτων είναι ένα αρχείο απλού κειμένου με ετικέτες οριοθετημένων περιοχών. Οι κενές γραμμές αγνοούνται, ενώ οι γραμμές που ξεκινούν με '#' αντιμετωπίζονται ως γραμμές σχολίων. Ενώ οι ετικέτες δείχνουν πως είναι ένα αρχείο xml, στην πραγματικότητα δεν είναι. Παρακαλούμε μην κλείνετε τις ετικέτες όπως <SUBSECTION>. Συμπερίληψη των δημιουργούμενων ενοτήτων <INCLUDE>libmeep/meep.h</INCLUDE> <SECTION> <FILE>meepapp</FILE> <TITLE>MeepApp</TITLE> MeepApp <SUBSECTION Standard> MEEP_APP ... MeepAppClass meep_app_get_type </SECTION> Η ετικέτα <FILE> ... </FILE> χρησιμοποιείται για να δηλώσει το όνομα του αρχείου, χωρίς οποιοδήποτε επίθημα. Παραδείγματος χάρη, η χρήση του '<FILE>gnome-config</FILE>' θα καταλήξει στην ενότητα δηλώσεων που εξάγονται στο αρχείο προτύπου tmpl/gnome-config.sgml, το οποίο θα μετατραπεί στο αρχείο DocBook XML xml/gnome-config.sgml ή στο αρχείο DocBook XML xml/gnome-config.xml. (Το όνομα του αρχείου HTML βασίζεται στο όνομα του αρθρώματος και τον τίτλο της ενότητας, ή για τα GObjects βασίζεται στο όνομα κλάσης GObjects που μετατράπηκε σε πεζά γράμματα). Η ετικέτα <TITLE> ... </TITLE> χρησιμοποιείται για να ορίσει τους τίτλους των ενοτήτων. Χρησιμεύει μόνο πριν τη δημιουργία των προτύπων, καθώς ο τίτλος που περιέχεται στα αρχεία προτύπων αντικαθιστά αυτούς τους τίτλους. Επίσης, αν χρησιμοποιείται το σχόλιο SECTION στον πηγαίο κώδικα, αυτό είναι παρωχημένο. Μπορείτε να ομαδοποιήσετε στοιχεία στην ενότητα χρησιμοποιώντας την ετικέτα <SUBSECTION>. Με την τωρινή της μορφή, εμφανίζει μία κενή γραμμή μεταξύ υποενοτήτων στη συνοπτική παρουσίαση. Μπορείτε επίσης να χρησιμοποιήσετε την <SUBSECTION Standard> για κλασικές δηλώσεις GObject (π.χ. συναρτήσεις όπως η g_object_get_type και μακροεντολές όπως οι G_OBJECT(), G_IS_OBJECT(), κτλ.). Προς το παρόν αυτές οι δηλώσεις μένουν εκτός τεκμηρίωσης. Μπορείτε να χρησιμοποιήσετε την ετικέτα <SUBSECTION Private> για ιδιωτικές δηλώσεις που δεν πρόκειται να εμφανιστούν στην τεκμηρίωση (έτσι αποφεύγετε τις προειδοποιήσεις για δηλώσεις που δεν χρησιμοποιούνται). Αν η βιβλιοθήκη σας περιέχει ιδιωτικούς τύπους, για τους οποίους δεν επιθυμείτε να εμφανίζονται στην ιεραρχία αντικειμένων και στη λίστα υλοποιημένων ή απαιτούμενων διεπαφών, προσθέσετε τους σε μία ιδιωτική υποενότητα. Αν θα τοποθετήσετε κλάσεις GObject και GObjectClass σε δημόσιες ή κλασσικές ενότητες εξαρτάται από το αν έχετε δημόσιες καταχωρήσεις (μεταβλητές,vmethods). Μπορείτε, επίσης, να χρησιμοποιήσετε την ετικέτα <INCLUDE> ... </INCLUDE> για τα αρχεία #include που περιλαμβάνονται στις ενότητες συνοπτικής παρουσίασης. Περιέχει μία λίστα με αρχεία #include, χωρισμένα με κόμματα και χωρίς τα '<' και '>'. Αν δεν τη χρησιμοποιήσετε στο εσωτερικό κάποιας ενότητας, θα αφορά όλες τις ενότητες μέχρι το τέλος του αρχείου. Αν τη χρησιμοποιήσετε στο εσωτερικό μιας ενότητας, τότε θα αφορά μόνο τη συγκεκριμένη ενότητα. Έλεγχος αποτελέσματος Κατά την εκτέλεση του GTK-Doc παράγονται αρχεία αναφορών που τοποθετούνται στον κατάλογο της τεκμηρίωσης. Πρόκειται για τα αρχεία: <package>-undocumented.txt, <package>-undeclared.txt και <package>-unused.txt. Είναι αρχεία απλού κειμένου, εύκολα στην ανάγνωση και επεξεργασία. Το αρχείο <package>-undocumented.txt ξεκινά με μία περίληψη της κάλυψης της τεκμηρίωσης. Ακολουθούν δύο ενότητες που χωρίζονται μεταξύ τους με κενές γραμμές. Η πρώτη ενότητα αναφέρει τα σύμβολα που δε διαθέτουν τεκμηρίωση ή είναι ημιτελή. Η δεύτερη καταγράφει τα ίδια στοιχεία για την τεκμηρίωση των ενοτήτων. Ημιτελείς θεωρούνται οι καταχωρήσεις για τις οποίες υπάρχει τεκμηρίωση, αλλά στις οποίες π.χ. προστέθηκε μια νέα παράμετρος. Το αρχείο <package>-undeclared.txt περιέχει σύμβολα που αναφέρονται στο αρχείο <package>-sections.txt, αλλά δε βρέθηκαν στον πηγαίο κώδικα. Θα πρέπει να ελέγξετε αν έχουν αφαιρεθεί ή αν περιέχουν συντακτικά λάθη. Το αρχείο <package>-unused.txt περιέχει ονόματα συμβόλων για τα οποία η σάρωση του GTK-Doc βρήκε τεκμηρίωση, αλλά δεν γνωρίζει πού να την τοποθετήσει. Aυτό σημαίνει ότι τα σύμβολα δεν έχουν προστεθεί ακόμη στο αρχείο <package>-sections.txt. Ενεργοποιήστε ή προσθέστε τη γραμμή στο Makefile.am. Αν έχετε εγκατεστημένη την έκδοση GTK-Doc 1.9 ή μεταγενέστερη, θα πραγματοποιεί διάφορους ελέγχους κατά την εκτέλεση του make check. Μπορείτε επίσης να δείτε τα αρχεία που παράγονται από το σαρωτή του πηγαίου κώδικα: <package>-decl-list.txt και <package>-decl.txt. Το πρώτο μπορεί να συγκριθεί με το αρχείο της ενότητας, αν αυτό συντηρείται χειροκίνητα. Το δεύτερο περιέχει όλες τις δηλώσεις από τις κεφαλίδες. Αν ένα σύμβολο λείπει μπορείτε να ελέγξετε αν περιέχεται σε αυτό το αρχείο. Αν το έργο βασίζεται στο GObject, μπορείτε επίσης να δείτε τα αρχεία που παράγονται από το σαρωτή αντικειμένων: <package>.args.txt, <package>.hierarchy.txt, <package>.interfaces.txt, <package>.prerequisites.txt και <package>.signals.txt. Αν υπάρχουν σύμβολα που λείπουν από οποιοδήποτε από αυτά, μπορείτε να ζητήσετε από το gtkdoc να κρατήσει το ενδιάμεσο αρχείο σάρωσης για περαιτέρω ανάλυση, εκτελώντας το ως μια εντολή GTK_DOC_KEEP_INTERMEDIATE=1 make. Εκσυγχρονίζοντας την τεκμηρίωση Το GTK-Doc κυκλοφορεί εδώ και αρκετό καιρό. Σε αυτό το κεφάλαιο θα παραθέσουμε τις νέες λειτουργίες μαζί με την έκδοση στην οποία είναι διαθέσιμες. GTK-Doc 1.9 Όταν χρησιμοποιείτε το xml αντί για το sgml, μπορείτε πράγματι να ονομάσετε το κύριο έγγραφο <package>-docs.xml. Αυτή η έκδοση υποστηρίζει στο Makefile.am. Αν αυτό ενεργοποιηθεί, το <package>-sections.txt αυτοδημιουργείται και μπορεί να αφαιρεθεί από το vcs. Αυτό λειτουργεί καλά μόνο για έργα που έχουν μια πολύ κανονική δομή (π.χ. το κάθε ζεύγος .{c,h} θα δημιουργεί μια νέα ενότητα). Αν κάποιος οργανώσει ένα έργο κοντά σε αυτό, τότε η ενημέρωση μιας ενότητας αρχείων που συντηρούνται χειρονακτικά μπορεί να είναι τόσο απλή όσο και το να εκτελούμε meld <package>-decl-list.txt <package>-sections.txt. Version 1.8 already introduced the syntax for documenting sections in the sources instead of the separate files under tmpl. This version adds options to switch the whole doc module to not use the extra tmpl build step at all, by using in configure.ac. If you don't have a tmpl checked into your source control system and haven't yet switched, just add the flag to configure.ac and you are done. GTK-Doc 1.10 Αυτή η έκδοση υποστηρίζει τα στο Makefile.am. Αν αυτό ενεργοποιηθεί, το <package>.types αυτοδημιουργείται και μπορεί να αφαιρεθεί από το vcs. Όταν χρησιμοποιείτε αυτή τη λειτουργία είναι σημαντικό να ρυθμίσετε και το IGNORE_HFILES στο Makefile.am για τον κώδικα που δομείται υπό όρους. GTK-Doc 1.16 Αυτή η έκδοση περιλαμβάνει ένα νέο εργαλείο που λέγεται gtkdoc-check. Αυτό το εργαλείο μπορέι να εκτελεί ένα σύνολο ελέγχων στην τεκμηρίωσή σας. Ενεργοποιείται προσθέτοντας αυτές τις γραμμές στο τέλος του Makefile.am. Ενεργοποίηση του gtkdoc-check if ENABLE_GTK_DOC TESTS_ENVIRONMENT = \ DOC_MODULE=$(DOC_MODULE) DOC_MAIN_SGML_FILE=$(DOC_MAIN_SGML_FILE) \ SRCDIR=$(abs_srcdir) BUILDDIR=$(abs_builddir) TESTS = $(GTKDOC_CHECK) endif GTK-Doc 1.20 Η έκδοση 1.18 έφερε μια αρχική υποστήριξη για το markdown. Η χρήση markdown στα σχόλια του doc είναι λιγότερο ενοχλητική από το να γράφει κανείς docbook xml. Αυτή η έκδοση επιφέρει μεγάλες βελτιώσεις σε αυτό και προσθέτει περισσότερα στυλ. Η ενότητα που εξηγεί τη σύνταξη σχολίων έχει όλες τις λεπτομέρειες. GTK-Doc 1.25 The makefiles shipped with this version generate an entity file at xml/gtkdocentities.ent, containing entities for e.g. package_name and package_version. You can use this e.g. in the main xml file to avoid hardcoding the version number. Below is an example that shows how the entity file is included in the master template and how the entities are used. The entities can also be used in all generated files, GTK-Doc will use the same xml header in generated xml files. Use pre-generated entities %gtkdocentities; ]> &package_name; Reference Manual for &package_string;. The latest version of this documentation can be found on-line at http://[SERVER]/&package_name;/. ]]> Τεκμηρίωση άλλων διεπαφών Μέχρ τώρα, χρησιμοποιούσαμε το GTK-Doc για να καταγράφουμε το API του κώδικα. Οι επόμενες συνεδρίες περιέχουν προτάσεις για το πώς τα εργαλεία μπορούν να χρησιμοποιηθούν για να καταγράφετε και άλλες διεπαφές. Επιλογές γραμμής εντολών και σελίδες τεκμηρίωσης man Δεδομένου ότι κάποιος μπορεί να παραγάγει σελίδες man για ένα docbook refentry επίσης, θα ήταν καλή ιδέα να χρησιμοποιηθεί και για αυτόν τον σκοπό. Με αυτόν τον τρόπο η διεπαφή γίνεται μέρος της αναφοράς και αποκτά δωρεάν την σελίδα-man. Τεκμηρίωση του εργαλείου Δημιουργήστε ένα refentry αρχείο ανά εργαλείο. Ακολουθώντας το παράδειγμά μας θα το ονομάσουμε meep/docs/reference/meeper/meep.xml. Για τις ετικέτες xml που πρέπει να χρησιμοποιηθούν και μπορούν να εξετάσουν το παραγόμενο αρχείο στον υποκατάλογο xml καθώς επίσης και τα παραδείγματα π.χ. στο glib. Προσθήκη του έξτρα ελέγχου διαμόρφωσης Επιπλέον έλεγχοι ρυθμίσεων AC_ARG_ENABLE(man, [AC_HELP_STRING([--enable-man], [regenerate man pages from Docbook [default=no]])],enable_man=yes, enable_man=no) AC_PATH_PROG([XSLTPROC], [xsltproc]) AM_CONDITIONAL(ENABLE_MAN, test x$enable_man != xno) Προσθήκη των επιπλέον κανόνων makefile Επιπλέον έλεγχοι ρυθμίσεων man_MANS = \ meeper.1 if ENABLE_GTK_DOC if ENABLE_MAN %.1 : %.xml @XSLTPROC@ -nonet http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl $< endif endif BUILT_EXTRA_DIST = $(man_MANS) EXTRA_DIST += meep.xml Διεπαφές DBus (FIXME: http://hal.freedesktop.org/docs/DeviceKit/DeviceKit.html, http://cgit.freedesktop.org/DeviceKit/DeviceKit/tree/doc/dbus) Συχνές ερωτήσεις Ερώτηση Απάντηση Δεν υπάρχει ιεραρχία κλάσεων. Η συνάρτηση αντικειμένου xxx_get_type() δεν έχει εισαχθεί στο αρχείο <package>.types Εξακολουθεί να μην υπάρχει ιεραρχία κλάσεων. Ελλιπής ή λανθασμένη ονομασία στο αρχείο <package>-sections.txt (δείτε την αιτιολόγηση). Στο καλό του, πάλι δεν έχω ιεραρχία κλάσεων. Ελέγξτε αν το όνομα του αντικειμένου (δηλαδή το όνομα του συγκεκριμένου παραδείγματος της δομής, π.χ. GtkWidget) περιλαμβάνεται στην κανονική ενότητα (δεν πρέπει να βρίσκεται εντός υποενότητας Standard ή Private). Δεν υπάρχει ευρετήριο συμβόλων. Το <package>-docs.{xml,sgml} περιέχει ένα ευρετήριο το οποίο περιλαμβάνει με xi:includes το παραγόμενο ευρετήριο; Δεν υπάρχουν σύνδεσμοι μεταξύ των συμβόλων και των κατάλληλων ενοτήτων της τεκμηρίωσης. Το doc-comment χρησιμοποιεί σωστά τις επισημάνσεις (έχουν προστεθεί #,% ή ()); Ελέγξτε αν το gtkdoc-fixxref προειδοποιεί για ανεπίλυτα xrefs. Μια νέα κλάση δεν εμφανίζεται στην τεκμηρίωση. Συμπεριλαμβάνεται η νέα σελίδα xi:included από το <package>-docs.{xml,sgml}; Ένα νέο σύμβολο δεν εμφανίζεται στην τεκμηρίωση. Το doc-comment είναι κανονικά μορφοποιημένο; Ελέγξτε για συντακτικά λάθη στην αρχή του σχολίου. Ελέγξτε αν το gtkdoc-fixxref προειδοποιεί για ανεπίλυτα xref. Ελέγξτε αν το σύμβολο είναι σωστά καταχωρημένο στο <package>-sections.txt σε μια δημόσια υποενότητα. Λείπει ένας τύπος από την ιεραρχία κλάσεων. Αν ο τύπος υπάρχει στο <package>.hierarchy αλλά όχι στο xml/tree_index.sgml τότε ελέγξτε ξανά ότι ο τύπος είναι σωστά τοποθετημένος στο <package>-sections.txt. Αν ο τύπος του παραδείγματος (π.χ. GtkWidget) δεν είναι καταχωρημένος, ή είναι κατά λάθος σημειωμένος ως ιδιωτικός, τότε δε θα εμφανιστεί. Λαμβάνω συνδέσμους foldoc για όλες τις σημειώσεις gobject. Ελέγξτε ότι το xml/annotation-glossary.xml είναι xi:included από το <package>-docs.{xml,sgml}. Μια παράμετρος περιγράφεται σε σχόλιο του πηγαίου κώδικα, αλλά δεν υπάρχει Ελέγξτε αν το πρωτότυπο στην κεφαλίδα περιέχει διαφορετικό όνομα για την παράμετρο από αυτό που αναφέρεται στον κώδικα. Πολλαπλά "Αναγνωριστικά" για τον προορισμό συνδέσμου: XYZ Το σύμβολο XYZ εμφανίζεται δύο φορές στο αρχείο <package>-sections.txt. Βρέθηκε το όνομα τύπου του στοιχείου στην ονοματοθεσία '', αλλά δεν αντιστοιχεί σε κανένα πρότυπο. Εργαλεία σχετικά με το gtk-doc GtkDocPlugin - ένα πρόσθετο ενσωμάτωσης Trac GTK-Doc, που προσθέτει έγγραφα API σε ιστοσελίδες trac και ενσωματώνεται με την αναζήτηση trac. Gtkdoc-depscan - ένα εργαλείο (μέρος του gtk-doc) για έλεγχο του χρησιμοποιούμενου API, επειδή οι ετικέτες στο API καθορίζουν την ελάχιστη απαιτούμενη έκδοση. Έκδοση 1.1, Μάρτιος 2000 2000Ίδρυμα Ελεύθερου Λογισμικού, Inc.
Free Software Foundation, Inc. 51 Franklin Street, Suite 330, Boston, MA 02110-1301 USA
Επιτρέπεται σε όλους η αντιγραφή και διανομή ακριβούς αντιγράφου του κειμένου αυτής της άδειας αλλά απαγορεύεται η αλλοίωση του περιεχομένου του. Άδεια Ελεύθερης Τεκμηρίωσης GNU (GFDL) 0. ΠΡΟΟΙΜΙΟ Σκοπός της παρούσας Άδειας είναι η δημιουργία εγχειριδίων, συγγραμμάτων ή άλλων εγγράφων που είναι ελεύθερα υπό την έννοια ότι παρέχουν σε όλους πραγματική ελευθερία αντιγραφής και αναδιανομής τους, με ή χωρίς τροποποιήσεις, για εμπορικούς ή μη εμπορικούς σκοπούς. Δευτερευόντως, η παρούσα Άδεια παρέχει έναν τρόπο για να αναγνωρίζεται το έργο του συγγραφέα και του εκδότη ενός έργου, χωρίς να μπορούν να θεωρηθούν υπεύθυνοι για τροποποιήσεις που έγιναν από τρίτους. Η παρούσα Άδεια είναι μια άδεια τύπου copyleft, το οποίο σημαίνει ότι τα παράγωγα έργα του εγγράφου θα πρέπει να είναι και αυτά ελεύθερα υπό την ίδια έννοια. Πρόκειται για άδεια συμπληρωματική της Γενικής Άδειας Δημόσιας Χρήσης GNU, που είναι άδεια copyleft σχεδιασμένη για ελεύθερο λογισμικό. Σχεδιάσαμε αυτήν την Άδεια για χρήση με εγχειρίδια ελεύθερου λογισμικού, γιατί το ελεύθερο λογισμικό χρειάζεται και ελεύθερη τεκμηρίωση: τα ελεύθερα προγράμματα πρέπει να συνοδεύονται από εγχειρίδια που παρέχουν τις ίδιες ελευθερίες που παρέχει και το λογισμικό. Ωστόσο, αυτή η Άδεια δεν περιορίζεται στα εγχειρίδια λογισμικού· μπορεί να χρησιμοποιηθεί για οποιοδήποτε έργο κειμένου, ανεξάρτητα από το θέμα του ή από το αν εκδίδεται σε έντυπη μορφή. Συνιστούμε αυτή την Άδεια, κυρίως, για διδακτικό υλικό ή έργα αναφοράς. 1. ΙΣΧΥΣ ΚΑΙ ΟΡΙΣΜΟΙ Η Άδεια αυτή εφαρμόζεται σε κάθε εγχειρίδιο ή άλλο έργο που περιέχει ένδειξη του δικαιούχου δικαιωμάτων πνευματικής ιδιοκτησίας, ότι επιτρέπεται η διανομή του υπό τους όρους αυτής της Άδειας. Ως Έγγραφο, κατωτέρω, αναφέρεται κάθε τέτοιο εγχειρίδιο. Ως κάτοχος της άδειας χρήσης θεωρείται κάθε άτομο, και αναφέρεται ως εσείς. Ως Τροποποιημένη Έκδοση του Εγγράφου θεωρείται κάθε έργο που περιέχει το Έγγραφο ή μέρος αυτού, είτε ως ακριβές αντίγραφο, είτε τροποποιημένο και/είτε μεταφρασμένο σε άλλη γλώσσα. Ως Δευτερεύουσα Ενότητα θεωρείται κάθε παράρτημα ή αρχική ενότητα του Εγγράφου που αναφέρεται αποκλειστικά στη σχέση των εκδοτών ή συγγραφέων του Εγγράφου με το συνολικό θέμα του Εγγράφου (ή σχετικά ζητήματα), και που δεν περιέχει οτιδήποτε μπορεί να θεωρηθεί ότι εντάσσεται άμεσα στο συνολικό αυτό θέμα. (Επί παραδείγματι, αν το Έγγραφο αποτελεί, εν μέρει, σύγγραμμα μαθηματικών, η Δευτερεύουσα Ενότητα δεν επιτρέπεται να επεξηγεί μαθηματικές έννοιες.) Η σχέση μπορεί να αποτελεί ιστορική σύνδεση με το θέμα ή σχετικά ζητήματα, ή νομική, εμπορική, φιλοσοφική, ηθική ή πολιτική θέση επί του θέματος ή σχετικών ζητημάτων. Αμετάβλητες Ενότητες είναι ορισμένες Δευτερεύουσες Ενότητες των οποίων οι τίτλοι αναφέρονται ρητώς ως τίτλοι Αμετάβλητων Ενοτήτων στην ένδειξη όπου αναφέρεται ότι το Έγγραφο δημοσιεύεται υπό τους όρους αυτής της Άδειας. Τα Κείμενα Εξωφύλλου είναι σύντομα αποσπάσματα κειμένου που αναφέρονται ρητώς ως Κείμενα Εμπροσθοφύλλου ή Κείμενα Οπισθοφύλλου στην ένδειξη όπου αναφέρεται ότι το Έγγραφο δημοσιεύεται υπό τους όρους αυτής της Άδειας. Ως Διαφανές αντίγραφο του Εγγράφου θεωρείται κάθε αντίγραφο σε μορφή αναγνώσιμη από μηχανή, όταν συντρέχουν οι εξής προϋποθέσεις: Οι τεχνικές προδιαγραφές τις μορφής αυτής είναι διαθέσιμες για δημόσια χρήση· τα περιεχόμενα του αντιγράφου μπορούν να προβληθούν και να τύχουν επεξεργασίας άμεσα και απλά, με χρήση γενόσημων επεξεργαστών κειμένου ή ( για εικόνες αποτελούμενες από εικονοστοιχεία) γενόσημων προγραμμάτων ζωγραφικής ή (για σχέδια) ευρέως διαθέσιμων επεξεργαστών σχεδίων· το αντίγραφο είναι κατάλληλο για είσοδο σε μορφοποιητές κειμένου ή για αυτόματη μετάφραση σε ποικίλες μορφές κατάλληλες για είσοδο σε μορφοποιητές κειμένου. Δεν θεωρείται Διαφανές ένα αντίγραφο σε Διαφανή, κατά τα λοιπά, μορφή αρχείου, του οποίου η επισήμανση έχει σχεδιαστεί κατά τρόπο που να αποτρέπει ή να αποθαρρύνει τη μελλοντική τροποποίηση του αντιγράφου από τους αναγνώστες. Το αντίγραφο που δεν είναι Διαφανές ονομάζεται Αδιαφανές. Παραδείγματα μορφών κατάλληλων για τη δημιουργία Διαφανών αντιγράφων είναι η απλή ASCII χωρίς επισήμανση, η μορφή εισόδου Texinfo, η μορφή εισόδου LaTeX, η SGML ή XML που χρησιμοποιούν δημοσίως διαθέσιμη DTD, και η HTML που συμμορφώνεται με πρότυπα και έχει σχεδιαστεί για τροποποίηση από τον άνθρωπο. Στις Αδιαφανείς μορφές συμπεριλαμβάνονται η PostScript, η PDF, οι ιδιοταγείς μορφές που αναγιγνώσκονται μόνο από ιδιοταγείς επεξεργαστές κειμένου, η SGML ή XML των οποίων η DTD και/ή τα εργαλεία επεξεργασίας δεν είναι δημοσίως διαθέσιμα, και η HTML με αποκλειστικό προορισμό την έξοδο που παράγουν μηχανοκίνητα ορισμένοι επεξεργαστές κειμένου. Ως Σελίδα Τίτλου θεωρείται, για τα έντυπα βιβλία, η σελίδα τίτλου αυτή καθαυτή, καθώς και τυχόν επόμενες σελίδες που απαιτούνται για την ευανάγνωστη συμπερίληψη του υλικού που οφείλει να εμφανίζεται στη σελίδα τίτλου σύμφωνα με την παρούσα Άδεια. Για τα έργα σε μορφές που δεν περιλαμβάνουν σελίδα τίτλου αυτή καθαυτή, ως Σελίδα Τίτλου θεωρείται το κείμενο που βρίσκεται κοντά στην εμφανέστερη εμφάνιση του τίτλου του έργου και το οποίο προηγείται του σώματος του κειμένου. 2. ΑΚΡΙΒΗ ΑΝΤΙΓΡΑΦΑ Σας χορηγείται άδεια αντιγραφής και διανομής του Εγγράφου σε οποιοδήποτε μέσο, για εμπορικό ή μη εμπορικό σκοπό, με την προϋπόθεση ότι σε κάθε αντίγραφο θα συμπεριλαμβάνετε την παρούσα Άδεια, τις ενδείξεις δικαιωμάτων πνευματικής ιδιοκτησίας και την ένδειξη άδειας χρήσης που αναφέρει ότι για το έγγραφο ισχύει η παρούσα Άδεια, και με την προϋπόθεση ότι δεν θα προσθέσετε κανένα επιπρόσθετο όρο πέρα από τους όρους της Άδειας. Δεν σας επιτρέπεται να χρησιμοποιήσετε τεχνικά μέτρα για την παρεμπόδιση ή τον έλεγχο της ανάγνωσης ή περαιτέρω αντιγραφής των αντιγράφων που δημιουργείτε ή διανέμετε. Ωστόσο, μπορείτε να αποδεχτείτε αποζημίωση σε αντάλλαγμα των αντιγράφων. Αν διανέμετε επαρκή αριθμό αντιγράφων, θα πρέπει να συμμορφωθείτε και με τους όρους της ενότητας 3. Επίσης, μπορείτε να δανείζετε αντίγραφα σύμφωνα με τους ως άνω όρους και να προβάλλετε δημοσίως τα αντίγραφα. 3. ΑΝΤΙΓΡΑΦΗ ΣΕ ΜΕΓΑΛΕΣ ΠΟΣΟΤΗΤΕΣ Αν εκδώσετε περισσότερα από 100 στον αριθμό έντυπα αντίγραφα του Εγγράφου, και η ένδειξη άδειας χρήσης του Εγγράφου προϋποθέτει την ύπαρξη Κειμένων Εξωφύλλου, θα πρέπει να εσωκλείσετε τα αντίγραφα σε εξώφυλλα που θα περιέχουν, με καθαρό και ευανάγνωστο τρόπο, όλα τα ακόλουθα κείμενα εξωφύλλου: Κείμενα Εμπροσθοφύλλου στο εμπροσθόφυλλο και Κείμενα Οπισθοφύλλου στο οπισθόφυλλο. Επίσης, και τα δύο εξώφυλλα θα πρέπει να αναφέρουν, καθαρά και ευανάγνωστα, εσάς ως εκδότη των αντιγράφων. Στο εμπροσθόφυλλο θα πρέπει να αναφέρεται ο πλήρης τίτλος του Εγγράφου, και όλες οι λέξεις του τίτλου θα πρέπει να είναι εξίσου προβεβλημένες και εμφανείς. Επιτρέπεται να προσθέσετε επιπρόσθετο υλικό στα εξώφυλλα. Η παραγωγή αντιγράφων που διαφέρουν μόνο ως προς τα εξώφυλλα, εφόσον διατηρείται ο τίτλος του Εγγράφου και τηρούνται οι παρούσες προϋποθέσεις, μπορεί να θεωρηθεί, κατά τα λοιπά, ως παραγωγή ακριβών αντιγράφων. Αν τα απαιτούμενα κείμενα ενός ή και των δύο εξωφύλλων είναι υπερβολικά μεγάλα για να παραμείνουν ευανάγνωστα αν συμπεριληφθούν σε μία σελίδα, θα πρέπει να τοποθετήσετε τα πρώτα εξώφυλλα του καταλόγου (όσα χωρούν κανονικά) στο εξώφυλλο αυτό καθ' αυτό, και να τοποθετήσετε τα υπόλοιπα στις γειτονικές σελίδες. Αν εκδώσετε περισσότερα από 100 στον αριθμό Αδιαφανή αντίγραφα του Εγγράφου, είτε θα πρέπει να συμπεριλάβετε ένα Διαφανές αντίγραφο (σε μορφή αναγνώσιμη από μηχανή) σε κάθε Αδιαφανές αντίγραφο, είτε θα πρέπει να αναφέρετε — μαζί ή σε κάθε Αδιαφανές αντίγραφο — μια δημοσίως προσβάσιμη τοποθεσία δικτύου υπολογιστών από την οποία θα μπορεί το ευρύ κοινό που χρησιμοποιεί δίκτυα να λάβει ανώνυμα, δωρεάν, και με χρήση πρωτοκόλλων δικτύου δημοσίων προτύπων, ένα ολοκληρωμένο Διαφανές αντίγραφο του Εγγράφου, χωρίς προσθήκες. Αν επιλέξετε τη δεύτερη επιλογή, όταν ξεκινήσετε τη διανομή των Αδιαφανών αντιγράφων, θα πρέπει να λάβετε λελογισμένα μέτρα για να διασφαλίσετε ότι το Διαφανές αντίγραφο θα παραμείνει προσβάσιμο στην ως άνωθεν τοποθεσία για τουλάχιστον ένα έτος μετά την τελευταία δημόσια διανομή Αδιαφανούς αντιγράφου αυτής της έκδοσης (είτε πρόκειται για άμεση διανομή είτε για διανομή μέσω των πρακτόρων ή λιανοπωλητών σας). Σας ζητείται, αλλά δεν απαιτείται, να επικοινωνήσετε εγκαίρως με τους συγγραφείς του Εγγράφου, πριν αναδιανείμετε μεγάλο αριθμό αντιγράφων, ώστε να έχουν τη δυνατότητα να σας παράσχουν αναθεωρημένη έκδοση του Εγγράφου. 4. ΤΡΟΠΟΠΟΙΗΣΕΙΣ Σας χορηγείται άδεια αντιγραφής και διανομής Τροποποιημένων Εκδόσεων του Εγγράφου υπό τους όρους των ενοτήτων 2 και 3 ανωτέρω, με την προϋπόθεση ότι θα δημοσιεύσετε την Τροποποιημένη Έκδοση υπό την παρούσα Άδεια ως έχει, όπου ως Έγγραφο θα νοείται η Τροποποιημένη Έκδοση. Άρα, θα χορηγείται άδεια διανομής και τροποποίησης της Τροποποιημένης Έκδοσης σε οποιονδήποτε κατέχει αντίγραφό της. Επιπροσθέτως, στην Τροποποιημένη Έκδοση θα πρέπει να κάνετε τα εξής: Α Στη Σελίδα Τίτλου (και τα εξώφυλλα, αν υφίστανται), χρησιμοποιήστε τίτλο διακριτό από τον τίτλο του Εγγράφου και των προηγούμενων εκδόσεών του (τυχόν προηγούμενες εκδόσεις οφείλουν να αναφέρονται στην ενότητα Ιστορικού του Εγγράφου). Μπορείτε να χρησιμοποιήσετε τον ίδιο τίτλο με τον τίτλο προηγούμενης έκδοσης, αν λάβετε άδεια από τον αρχικό εκδότη της προηγούμενης έκδοσης. Β Αναφέρετε στη Σελίδα Τίτλου, υπό την ιδιότητα του συγγραφέα, όλα τα άτομα ή τους φορείς που ευθύνονται για τη συγγραφή ή την τροποποίηση της Τροποποιημένης Έκδοσης, μαζί με τουλάχιστον πέντε από τους κύριους συγγραφείς του Εγγράφου ( ή όλους τους κύριους συγγραφείς, αν είναι λιγότεροι από πέντε). Γ Αναφέρετε στη Σελίδα Τίτλου, υπό την ιδιότητα του εκδότη, το όνομα του εκδότη της Τροποποιημένης Έκδοσης. Δ Διατηρήστε όλες τις ενδείξεις δικαιωμάτων πνευματικής ιδιοκτησίας του Εγγράφου. Ε Προσθέστε την κατάλληλη ένδειξη δικαιωμάτων πνευματικής ιδιοκτησίας για τις τροποποιήσεις σας στις υπόλοιπες ενδείξεις δικαιωμάτων πνευματικής ιδιοκτησίας. ΣΤ Συμπεριλάβετε, αμέσως μετά τις ενδείξεις δικαιωμάτων πνευματικής ιδιοκτησίας, μια ένδειξη άδειας χρήσης που θα χορηγεί δημόσια άδεια χρήσης της Τροποποιημένης Έκδοσης υπό τους όρους της παρούσας Άδειας. Η μορφή της ένδειξης αυτής παρατίθεται στο Συμπλήρωμα που ακολουθεί. Ζ Διατηρήστε σε αυτή την ένδειξη άδειας χρήσης τους πλήρεις καταλόγους Αμετάβλητων Ενοτήτων και απαιτούμενων Κειμένων Εξωφύλλου που παρατίθενται στην ένδειξη άδειας χρήσης του Εγγράφου. Η Συμπεριλάβετε αντίγραφο, χωρίς τροποποιήσεις, της παρούσας Άδειας. Θ Διατηρήστε την ενότητα με τίτλο Ιστορικό, καθώς και τον τίτλο της, και προσθέστε μία εγγραφή που θα αναφέρει τουλάχιστον τον τίτλο, το έτος, τους νέους συγγραφείς και τον εκδότη της Τροποποιημένης Έκδοσης όπως αυτά αναφέρονται στη Σελίδα Τίτλου. Αν δεν υπάρχει ενότητα με τίτλο Ιστορικό στο Έγγραφο, δημιουργήστε αυτήν την ενότητα, αναγράφοντας τον τίτλο, το έτος, τους νέους συγγραφείς και τον εκδότη του Εγγράφου, όπως αυτά αναφέρονται στη Σελίδα Τίτλου, και προσθέτοντας μία εγγραφή που θα περιγράφει την Τροποποιημένη Έκδοση σύμφωνα με την προηγούμενη πρόταση. Ι Διατηρήστε την τοποθεσία δικτύου που ενδεχομένως παρέχεται στο Έγγραφο για δημόσια πρόσβαση σε Περατό αντίγραφο του Εγγράφου, καθώς και τυχόν άλλες τοποθεσίες δικτύου που παρέχονται στο έγγραφο και αφορούν προηγούμενες εκδόσεις του. Οι τοποθεσίες αυτές μπορούν να τοποθετηθούν στην ενότητα Ιστορικό. Μπορείτε να παραλείψετε τοποθεσίες δικτύου για έργα που εκδόθηκαν τουλάχιστον τέσσερα έτη πριν από το ίδιο το Έγγραφο, ή αν ο αρχικός εκδότης της αντίστοιχης έκδοσης σας δώσει την άδεια. ΙΑ Αν υπάρχει ενότητα με τίτλο Ευχαριστίες ή Αφιέρωση, διατηρήστε τον τίτλο της ενότητας, και διατηρήστε στο σώμα της ενότητας την ουσία και το ύφος των ευχαριστιών και/ή αφιερώσεων που συμπεριλαμβάνονται σε αυτή. ΙΒ Διατηρήστε όλες τις Αμετάβλητες Ενότητες του Εγγράφου, χωρίς καμία τροποποίηση στο κείμενο και τον τίτλο τους. Η αρίθμηση των ενοτήτων, —ή άλλο ισοδύναμό της—, δεν θεωρείται τμήμα του τίτλου των ενοτήτων. ΙΓ Διαγράψτε τυχόν ενότητες με τίτλο Έγκριση. Αυτού του είδους οι ενότητες δεν επιτρέπεται να συμπεριληφθούν στην Τροποποιημένη Έκδοση. ΙΔ Μην αλλάζετε τον τίτλο καμίας προϋπάρχουσας ενότητα σε Έγκριση ή σε τίτλο που να συγκρούεται με τον τίτλο οποιασδήποτε Αμετάβλητης Ενότητας. Αν η Τροποποιημένη Έκδοση περιλαμβάνει νέες αρχικές ενότητες ή παραρτήματα, που εμπίπτουν στον ορισμό των Δευτερευουσών Ενοτήτων, και δεν περιέχουν υλικό που να είναι προϊόν αντιγραφής του Εγγράφου, μπορείτε, εφόσον το επιθυμείτε, να ορίσετε ορισμένες ή όλες αυτές τις ενότητες ως αμετάβλητες. Για να το πράξετε, προσθέστε τους τίτλους αυτών των ενοτήτων στον κατάλογο Αμετάβλητων Ενοτήτων στην ένδειξη άδειας χρήσης της Τροποποιημένης Έκδοσης. Οι τίτλοι αυτοί θα πρέπει να είναι διακριτοί από τους υπόλοιπους τίτλους ενοτήτων.. Μπορείτε να προσθέσετε ενότητα με τίτλο Έγκριση, με την προϋπόθεση ότι περιλαμβάνει αποκλειστικά εγκρίσεις της δικής σας Τροποποιημένης Έκδοσης από διάφορους φορείς, —επί παραδείγματι, δηλώσεις αξιολόγησης ομοτίμων ή δηλώσεις ότι το κείμενο έχει εγκριθεί από έναν οργανισμό ως έγκυρος ορισμός ενός προτύπου. Μπορείτε να προσθέσετε κείμενο μέχρι και πέντε λέξεις ως Κείμενο Εμπροσθοφύλλου, καθώς και κείμενο μέχρι και 25 λέξεις ως Κείμενο Οπισθοφύλλου, στο τέλος του καταλόγου Κειμένων Εξωφύλλου της Τροποποιημένης Έκδοσης. Κάθε μεμονωμένος φορέας επιτρέπεται να προσθέτει μόνο ένα Κείμενο Εμπροσθοφύλλου και ένα Κείμενο Οπισθοφύλλου (ο ίδιος ή εξ ονόματος του ίδιου). Αν το Έγγραφο περιέχει ήδη κείμενο εξωφύλλου για το ίδιο εξώφυλλο, —που είχατε προσθέσει προηγουμένως είτε εξ ονόματός σας είτε εξ ονόματος του φορέα που εκπροσωπείτε—, δεν σας επιτρέπεται να προσθέσετε επιπλέον εξώφυλλο· σας επιτρέπεται ωστόσο να αντικαταστήσετε το προηγούμενο, με ρητή άδεια από τον εκδότη που είχε προσθέσει το προηγούμενο εξώφυλλο. Μέσω της παρούσας άδειας, ο/οι συγγραφείς και ο/οι εκδότες του Εγγράφου δεν χορηγούν άδεια χρήσης των ονομάτων τους για διαφημιστικούς σκοπούς ή για την έγκριση, —ρητή ή υπονοούμενη—, οποιασδήποτε Τροποποιημένης Έκδοσης. 5. ΣΥΝΔΥΑΣΜΟΣ ΕΓΓΡΑΦΩΝ Μπορείτε να συνδυάσετε το Έγγραφο με άλλα έγγραφα που υπόκεινται στους όρους της παρούσας Άδειας, σύμφωνα με τους ανωτέρω όρους της ενότητας 4 για τις τροποποιημένες εκδόσεις, με την προϋπόθεση ότι ο συνδυασμός θα περιλαμβάνει όλες τις Αμετάβλητες Ενότητες όλων των πρωτότυπων εγγράφων, χωρίς τροποποιήσεις, και ότι θα αναφέρονται ως Αμετάβλητες Ενότητες του συνδυασμένου έργου στην ένδειξη άδειας χρήσης του. Το συνδυασμένο έργο οφείλει να περιέχει ένα μόνο αντίγραφο της παρούσας Άδειας, και επιτρέπεται η αντικατάσταση πολλαπλών ταυτόσημων Αμετάβλητων Ενοτήτων από ένα μόνο αντίγραφό τους. Αν υφίστανται πολλαπλές Αμετάβλητες Ενότητες με τον ίδιο τίτλο αλλά διαφορετικό περιεχόμενο, φροντίστε να κατασταθεί μοναδικός ο τίτλος κάθε ενότητας, προσθέτοντας στο τέλος του τίτλου, εντός παρενθέσεων, το όνομα του αρχικού συγγραφέα ή εκδότη της ενότητας εφόσον τα γνωρίζετε, ή, εναλλακτικά, ένα μοναδικό αριθμό. Φροντίστε να κάνετε τις ίδιες αλλαγές στους τίτλους των ενοτήτων που αναγράφονται στον κατάλογο Αμετάβλητων Ενοτήτων στην ένδειξη άδειας χρήσης του συνδυασμένου έργου. Στο συνδυασμό θα πρέπει να συνδυάσετε όλες τις ενότητες με τίτλο Ιστορικό που ενδεχομένως διαθέτουν τα πρωτότυπα έγγραφα, δημιουργώντας μία μοναδική ενότητα με τίτλο Ιστορικό. Κατά τον ίδιο τρόπο θα πρέπει να συνδυάσετε και όλες τις ενότητες με τίτλο Ευχαριστίες ή όλες τις ενότητες με τίτλο Αφιέρωση. Θα πρέπει να διαγράψετε όλες τις ενότητες με τίτλο Έγκριση. 6. ΣΥΛΛΟΓΗ ΕΓΓΡΑΦΩΝ Μπορείτε να δημιουργήσετε συλλογή που θα περιλαμβάνει το παρόν Έγγραφο μαζί με άλλα έγγραφα που υπόκεινται στους όρους της παρούσας Άδειας, και να συμπεριλάβετε στη συλλογή ένα μόνο αντίγραφο της παρούσας Άδειας, που θα αντικαθιστά τα μεμονωμένα αντίγραφά της στα διάφορα έγγραφα, με την προϋπόθεση ότι, κατά τα λοιπά, θα συμμορφωθείτε με τους κανόνες της παρούσας Άδειας για την παραγωγή πιστών αντιγράφων καθενός από αυτά τα έγγραφα. Μπορείτε να εξάγετε ένα μεμονωμένο έγγραφο από μια συλλογή τέτοιου είδους, και να το διανείμετε ξεχωριστά υπό τους όρους της παρούσας Άδειας, με την προϋπόθεση ότι θα προσθέσετε αντίγραφο της παρούσας Άδειας στο εξαχθέν έγγραφο, και ότι, κατά τα λοιπά, θα συμμορφωθείτε με τους κανόνες της παρούσας Άδειας για την παραγωγή ακριβών αντιγράφων αυτού του εγγράφου. 7. ΣΥΡΡΑΦΗ ΜΕ ΑΝΕΞΑΡΤΗΤΑ ΕΡΓΑ Αν το Εγγράφο ή τα παράγωγά του συμπεριληφθούν, μαζί με άλλα ξεχωριστά και ανεξάρτητα έγγραφα ή έργα, σε τόμο ενός μέσου αποθήκευσης ή διανομής, ο τόμος αυτός, στο σύνολό του, δεν θεωρείται Τροποποιημένη Έκδοση του εγγράφου, με την προϋπόθεση ότι δεν διεκδικούνται δικαιώματα πνευματικής ιδιοκτησίας για αυτόν. Ο εν λόγω τόμος ονομάζεται συρραφή και η παρούσα άδεια δεν ισχύει για τα υπόλοιπα αυθύπαρκτα έργα που συμπεριλαμβάνονται σε αυτόν, πέραν του Έγγραφο, απλώς και μόνο επειδή ανήκουν σε αυτή τη συρραφή, εκτός εάν αποτελούν και αυτά παράγωγα έργα του Εγγράφου. Αν για αυτά τα αντίγραφα του Εγγράφου ισχύουν οι όροι για τα Κείμενα Εξωφύλλου της ενότητας 3, τότε, αν το Έγγραφο αντιστοιχεί σε λιγότερο από το ένα τέταρτο του συνόλου της συρραφής, τα Κείμενα Εξωφύλλου του Εγγράφου επιτρέπεται να τοποθετηθούν σε εξώφυλλα εντός της συρραφής που εσωκλείουν μόνο το Έγγραφο. Ειδάλλως, θα πρέπει να τοποθετηθούν σε εξώφυλλα που εσωκλείουν ολόκληρη τη συρραφή. 8. ΜΕΤΑΦΡΑΣΗ Η μετάφραση θεωρείται μορφή τροποποίησης, άρα μπορείτε να διανέμετε μεταφράσεις του Εγγράφου υπό τους όρους της ενότητας 4. Η αντικατάσταση των Αμετάβλητων Ενοτήτων από μεταφράσεις απαιτεί ειδική άδεια από τους κατόχους των δικαιωμάτων πνευματικής ιδιοκτησίας, αλλά επιτρέπεται η συμπερίληψη στο Έγγραφο μεταφράσεων ορισμένων ή όλων των Αμετάβλητων Ενοτήτων, επιπλέον των πρωτότυπων εκδόσεων αυτών των Αμετάβλητων Ενοτήτων. Μπορείτε να προσθέσετε μεταφράσεις της παρούσας Άδειας, με την προϋπόθεση ότι θα συμπεριλάβετε και την πρωτότυπη Αγγλική έκδοση της Άδειας. Σε περίπτωση ασυμφωνίας μεταξύ μετάφρασης και πρωτότυπης Αγγλικής έκδοσης της Άδειας, ισχύει η πρωτότυπη Αγγλική έκδοση. 9. ΚΑΤΑΡΓΗΣΗ Δεν σας επιτρέπεται η αντιγραφή, τροποποίηση, περαιτέρω παραχώρηση άδειας εκμετάλλευσης ή διανομή του Εγγράφου παρά μόνο με τον τρόπο που ρητά προβλέπεται από αυτήν την Άδεια. Κάθε άλλη απόπειρα αντιγραφής, τροποποίησης, περαιτέρω παραχώρησης άδειας εκμετάλλευσης ή διανομής του Εγγράφου είναι άκυρη και αυτομάτως καταργεί τα δικαιώματα που σας παραχωρεί η παρούσα Άδεια. Ωστόσο, τα μέρη στα οποία παρείχατε αντίγραφα ή δικαιώματα υπό τους όρους της παρούσας Άδειας, δεν θα απωλέσουν τα δικαιώματα χρήσης τους, εφόσον εξακολουθούν να συμμορφώνονται πλήρως με τους όρους της Άδειας. 10. ΜΕΛΛΟΝΤΙΚΕΣ ΑΝΑΘΕΩΡΗΣΕΙΣ ΤΗΣ ΠΑΡΟΥΣΑΣ ΑΔΕΙΑΣ Το Ίδρυμα Ελεύθερου Λογισμικού έχει το δικαίωμα να δημοσιεύει περιστασιακά αναθεωρημένες ή/και νέες εκδόσεις της Ελεύθερης Άδειας Τεκμηρίωσης GNU (GFDL). Αυτές οι νέες εκδόσεις θα είναι συναφείς στο πνεύμα με την παρούσα έκδοση, όμως ενδέχεται να διαφέρουν στις λεπτομέρειες, καθώς επιλαμβάνονται νέων προβλημάτων και ζητημάτων. Βλέπε http://www.gnu.org/copyleft/. Σε κάθε έκδοση δίνεται ένας διακριτικός αριθμός έκδοσης. Εάν στο Έγγραφο καθορίζεται ότι ισχύει ένας συγκεκριμένος αριθμός έκδοσης της παρούσας Άδειας ή οποιαδήποτε μεταγενέστερη έκδοση, μπορείτε να επιλέξετε μεταξύ των όρων και προϋποθέσεων είτε αυτής της έκδοσης, είτε οποιασδήποτε μεταγενέστερης έκδοσης έχει δημοσιευτεί (όχι με μορφή σχεδίου) από το Ίδρυμα Ελεύθερου Λογισμικού. Εάν στο Πρόγραμμα δεν καθορίζεται αριθμός έκδοσης της Άδειας, μπορείτε να επιλέξετε οποιαδήποτε έκδοση έχει δημοσιευθεί (όχι με μορφή σχεδίου) από το Ίδρυμα Ελεύθερου Λογισμικού (FSF). Συμπλήρωμα Για να χρησιμοποιήσετε την παρούσα Άδεια σε έγγραφο το οποίο συγγράψατε, θα πρέπει να συμπεριλάβετε ένα αντίγραφο της Άδειας στο έγγραφο και να τοποθετήσετε τις ακόλουθες ενδείξεις δικαιωμάτων πνευματικής ιδιοκτησίας και άδειας χρήσης αμέσως μετά τη σελίδα τίτλου:
Copyright © ΕΤΟΣ ΤΟ ΟΝΟΜΑ ΣΑΣ. Χορηγείται άδεια αντιγραφής, διανομής και/ή τροποποίησης του παρόντος εγγράφου υπό τους όρους της έκδοσης 1.1 της Ελεύθερης Άδειας Τεκμηρίωσης GNU (GFDL), ή οποιασδήποτε μεταγενέστερης έκδοσής αυτής από το Ίδρυμα Ελεύθερου Λογισμικού (FSF)· οι Αμετάβλητες Ενότητες είναι οι ΚΑΤΑΛΟΓΟΣ ΤΙΤΛΩΝ, τα Κείμενα εμπροσθοφύλλου είναι τα ΚΑΤΑΛΟΓΟΣ, και τα Κείμενα Οπισθοφύλλου είναι τα ΚΑΤΑΛΟΓΟΣ. Αντίγραφο της άδειας συμπεριλαμβάνεται στην ενότητα με τίτλο GNU Free Documentation License.
Αν δεν περιέχονται Αμετάβλητες Ενότητες, γράψτε χωρίς Αμετάβλητες Ενότητες, αντί να απαριθμήσετε τις αμετάβλητες ενότητες. Αν δεν περιέχονται Κείμενα Εμπροσθοφύλλου, γράψτε χωρίς Κείμενα Εμπροσθοφύλλου αντί για τα Κείμενα Εμπροσθοφύλλου είναι τα ΚΑΤΑΛΟΓΟΣ· ομοίως για τα Κείμενα Οπισθοφύλλου. Αν το έγγραφό σας περιέχει μη ασήμαντα παραδείγματα πηγαίου κώδικα, συνιστούμε την παράλληλη δημοσίευσή τους υπό τους όρους της άδειας ελεύθερου λογισμικού της αρεσκείας σας, ώστε να επιτρέψετε τη χρήση τους σε ελεύθερο λογισμικό. Παράδειγμα τέτοιας άδειας αποτελεί η Γενική Άδεια Δημόσιας Χρήσης GNU.