podofo: init at 0.9.6

.editorconfig

@@ -0,0 +1,11 @@
+[*.{cpp,h,hpp}]
+end_of_line = lf
+charset = utf-8
+indent_style = space
+indent_size = 4
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.txt]
+end_of_line = lf
+charset = utf-8

AUTHORS

@@ -0,0 +1,8 @@
+PoDoFo library, tools and tests:
+	Dominik Seichter <[email protected]>
+	Leonard Rosenthol <[email protected]>
+	Craig Ringer <[email protected]>
+
+PoDoFoImpose:
+	Contributed by Pierre Marchand <[email protected]> as `pdfimpose'
+	Qt-to-STL conversion by Craig Ringer <[email protected]>

CODINGSTYLE.txt

@@ -0,0 +1,333 @@
+This document tries to give an overview of the codingstyle used in PoDoFo.
+To keep the code consistent every commit should apply to this codingstyle.
+
+The codingstyle of PoDoFo is in no way perfect and is in parts not even the
+preferred codingstyle of the maintainers. But consistency is more important
+than personal preferences and most parts of the style can be applied through
+simple editor settings.
+
+       2006 Dominik Seichter <[email protected]> 
+
+0. Overall Rule
+===============
+
+    Documentation is an important part of PoDoFo. Every class and method
+    should include appropriate documentation in Doxygen format so that
+    automatic API documentation can be generated and the code can be
+    easily understand by everyone.
+
+    The comments are most important in the header files, though additional
+    information may also be included in the source itself if necessary.  
+
+1. Code formatting
+==================
+
+1.1 Indentation
+
+     The code is indented by 4 spaces. No tabs and no discussion ;)
+     EMACS users might apply those settings:
+         (setq tab-width 4)                    ;; the the preferred tab-width
+         (setq indent-tabs-mode nil)           ;; indent using spaces instead of tabs
+         (setq c-basic-offset tab-width)
+
+1.2 Brackets
+
+    Brackets always start in a new line of their own. The only exception are
+    class and struct declarations and try and catch blocks.
+
+    Example:
+
+    if( true ) 
+    {
+         // do something
+    }
+
+    but 
+
+    class MyClass {
+
+    };
+
+    If only one line follows after an if or while statement, no brackets are
+    needed, however they may be used if the author feels that there is a 
+    possibility for future expansion in that area.
+
+
+1.3 Inline functions
+
+    Inline functions are declared in the class definition in the header file.
+    They are implemented in the header file after the class definition.  
+    The author may choose to either implement them directly at the same location
+    as the declaration or may place them at the end of the header file (preferred).
+
+2. Naming
+=========
+
+2.1 Variables
+
+    Someone started to use hungarian notation in PoDoFo. Well, the maintainer
+    thinks this was one of the worst ideas he ever had... . Nontheless, the
+    point is consistency and not personall preference. 
+
+    PoDoFo uses hungarian notation for the following types:
+
+    enum typenames	  should start with an			E
+    enum variables	  should start with an			e
+    struture typesnames	  should start with a			T
+    struture variables	  should start with a			t
+    pointer		  should start with a			p
+    strings		  should start with a			s
+    c-strings		  should start with			psz
+(pointer zero terminated)
+    numbers		  should start with a			n
+    long's		  should start with a			l
+    bool's		  should start with a			b
+    references            often  start with a                   r
+
+    Example:
+
+    bool  bDecision;
+    long  lValue;
+    char* pszString;
+    int   nNumber;
+
+2.2 Member variables
+
+    Member variables in classes are additionally prefixed with "m_".
+
+    Examples:
+
+    class MyClass {
+
+    private:
+    bool m_bMemberVar;
+
+    };
+
+2.3 Methods
+
+    All methods start with an uppercase letter and every new word is
+    capitalized again.
+
+    MyClass::FunctionWithLongName( long lParameter );
+
+    Properties are set using a function with the prefix "Set", and retrieved with
+    a "Get".   Also, unless there is a good reason not to - all "Getters" should be
+    marked as const.
+
+    MyClass::SetProperty( long lValue );
+    long MyClass::GetProperty() const;
+
+    Additionally, please use the prefixes "Has" and "Is" when appropriate.
+    E.g.
+
+    PdfDictionary::HasKey();
+    PdfDocument::IsLinearized();
+
+    Avoid the throw() qualifier (see 3.5).
+
+2.4 NULL-Pointers
+
+    NULL Pointers are initialized in the code with the constant NULL. Please
+    do not use 0 or 0L but use NULL.
+
+3. General Guidelines
+===================
+
+3.1 Casting
+
+    C++ style casting is strongly preferred, and the use of C-style casts will
+    generate warnings on gcc builds. Use, as appropriate,
+        static_cast<>
+        const_cast<>
+        reinterpret_cast<>
+    Dynamic casting and typeid are not presently used in PoDoFo.
+
+    const_cast<> should be avoided unless it is absolutely required, especially
+    for `const char *' variables that might ever take a string literal value.
+
+3.2 Local variable declaration
+
+    Local variables should always be declared closest to their point of use,
+    and should be declared `const' wherever possible.
+
+    For example:
+
+    Thing f()
+    {
+       Thing ret;
+       // blah blah blah
+       ret = DoSomething();
+       // blah blah blah
+       return ret;
+    }
+
+    would be better written as:
+
+    Thing f()
+    {
+       // blah blah blah
+       Thing ret ( DoSomething() );
+       // blah blah blah
+       return ret;
+    }
+
+    Remember your const pointers:
+
+    char * x;               Pointer to char
+    const char * x;         Pointer to const char
+    char * const x;         Const pointer to char
+    const char * const x;   Const pointer to const char
+
+3.3 Static arrays
+
+    Static data should be declared as an array of const char rather than a
+    pointer to const char whereever possible. This will help the compiler put
+    it in the static read only data section of the compiled object, resulting
+    in a smaller memory footprint, faster load times, and hardware protection
+    against accidental writes to the data.
+
+    const char myStaticData[] = "This is the right way".
+    const char * myStaticData = "Avoid this way".
+
+    Two dimensional arrays may be specified in a similar way - see
+    s_szPdfVersions in PdfDefines.{cpp,h} . It's usually better to waste a few
+    bytes by padding the array to the length of the longest member and get it
+    into the readonly data section of the executable than it is to use an array
+    of pointers to char and save a few bytes. Which is best is, however, dependent
+    on what "a few bytes" is in a given situation.
+
+3.4 Use of temporary objects
+
+    Where possible, it can be better to use a temporary rather than
+    storing a named object, eg:
+
+    DoSomething( PdfName("blah") );
+
+    rather than
+
+    PdfName n("blah");
+    DoSomething( n );
+
+    as this makes it easier for the compiler to optimise the call, may reduce
+    the stack size of the function, etc. Don't forget to consider the lifetime
+    of the temporary, however.
+
+3.5 The `throw' qualifier
+
+    Under no circumstances use exception specifiers, even the empty exception
+    specifier `throw()'. C++ checked exceptions - when implemented according
+    to the standard - are essentially useless and may actually be costly. If
+    you want to tell the compiler a method will not throw (as an optimisation)
+    use a macro for __declspec(nothrow) instead. podofoapi provides
+    appropriate macros for use in podofo. (Note that VC++ treats throw() as
+    __declspec(nothrow) in violation of the standard, but that's all the more
+    reason to just use __declspec(nothrow)).
+
+    see:
+    http://msdn2.microsoft.com/en-us/library/49147z04.aspx
+    http://gcc.gnu.org/onlinedocs/gcc-3.3.1/gcc/Function-Attributes.html
+
+3.6 Exported API
+
+    PoDoFo draws a distinction between exported and private API on some
+    platforms (currently Windows DLL builds and gcc 4 with
+    PODOFO_USE_VISIBILITY). To do this it uses some macros defined in
+    podofoapi.h to tell the compiler what's public API that should appear
+    in the DLL/shared library's symbol table. The rest is not exported.
+
+    This may have several positive effects depending on the particular
+    platform and compiler. It can result in a smaller binary, better link
+    times, help the compiler optimise better, and ensure that API intended to
+    be private to PoDoFo _cannot_ be called from outside it.
+
+    If you add new classes to PoDoFo, annotate them with PODOFO_API
+    as shown in podofoapi.h if they're intended as public API. If an outside
+    user will ever need to reference those symbols directly (by constructing
+    the class, calling its methods, etc) they're public.
+
+    Note that classes that only inherit and implement an abstract interface
+    (adding no other public methods intended for use outside PoDoFo) that're
+    only constructed through a factory or through other PoDoFo classes need
+    not be exported.
+
+    If you have a class that needs to be exported as public API, but it has
+    quite a few methods that do not need to be externally visible (private
+    helper methods etc), you can annotate those with the PODOFO_LOCAL macro as
+    shown in podofoapi.h . This omits just those methods from the symbol
+    table. Note that if the methods are accessed via public or protected
+    inline functions it is not safe to make them private.
+
+    If in doubt, ask for help on podofo-users. It also helps to build PoDoFo
+    as a DLL (Windows) or, on UNIX platforms, use gcc4 and enable visibility
+    support. This will help catch cases where you forgot to export required
+    API.
+
+3.7 Memory allocations in inlined methods
+
+    It's not safe to (directly) allocate or free
+    heap memory in an inlined function, because it only works if the same
+    runtime library is used in the shared library and the executable linking
+    to the library. Using malloc and/or new in inlined methods will lead to
+    crashes on MS Windows systems. It might be undetected on Linux systems
+    (even though it is bad style on Linux, too), because most processes and
+    libraries use the same runtime library on a Linux system.
+
+    There's also no point inlining functions that call new / delete /
+    malloc / free, because the memory allocation is dramatically more
+    expensive than a mere function call is.
+
+    Using STL classes that may perform allocations internally is fine since
+    they tend to carry their own std::allocator instance (or reference,
+    anyway) around with them.
+
+3.8 Visibility of 3rd party headers
+
+    If at all possible, it's desirable not to expose the use of 3rd party
+    headers in the PoDoFo headers. Rather than including headers for required
+    libraries, try to forward-declare required types and then include the
+    header in the implementation (.cpp) files. If the header is widely used,
+    you might want to put it in PdfDefinesPrivate.h . Widely used forward
+    declarations can go in Pdf3rdPtyForwardDecl.h .
+
+    Avoiding exposing used 3rd party headers means that users' build systems
+    don't need to know how to find those headers, and means that users' programs
+    don't get their namespaces polluted by unrelated symbols from libjpeg,
+    zlib, libtiff, freetype, etc etc etc. As some headers (*cough*freetype*cough*)
+    aren't trivial to reliably locate, this can really simplify the build of
+    tools that use PoDoFo.
+
+    This applies to some system headers too. <windows.h> for example is a
+    difficult and quirky header. Its behaviour is strongly affected by
+    a variety of preprocessor definitions and it scatters macros everywhere.
+    We shouldn't be exposing it to library users, because it's quite likely
+    they'll need to include it with different macro parameters, and theirs
+    may conflict with ours or vice versa.
+
+    If you need to include a 3rd party header to make something a direct
+    member, consider making it a member by pointer instead, initializing
+    it in the object's ctor and destroying it it the dtor. That way you
+    don't need to include the 3rd party's header to get access to their
+    type sizes in the PoDoFo headers, only in the .cpp files. See, for example,
+    PdfMutex.h .
+
+4. Structure
+============
+
+4.1 Project structure
+
+The PoDoFo project is structure as follows. 
+
+There are two libraries: podofo-base and podofo-doc. Podofo-base contains
+everythign needed to work with reading, writing and modifying PDF files and
+there objects. It should have a minimal set of dependencies. Podofo-doc
+provides a rich interface, which also allows to easily create PDF files using
+the PdfPainter and PdfFont infrastructure. 
+
+Additionally, there are two more projects. The test/ subdirectory contains
+tests for both libraries. All new tests shall go to the test/unit/
+sub-projects to provide unit-tests for PoDoFo. Utility programs that come with
+PoDoFo go into the tools/ subdirectory. These tools provide a direct benefit
+for end users who want to work with PDF files on the commandline and are also
+a nice way to showcase the features of the PoDoFo libraries to new
+developers.