wiki:PublicanBetaAnnounce
Last modified 4 years ago Last modified on 01/27/10 16:48:54

Publican Beta 1.0 Release Notes

Developer Notes

Tasks

Overview:

Publican is a software toolchain that processes docbook xml to multiple outputs.

  • The first version of publican in the 0.x development stream mainly used GNU make. The 1.x version of publican uses perl. The primary advantages are speed, portability, modularity and fewer dependencies.
  • Previous reliance on KDE tools xml2pot and po2xml has been completely removed and replaced by perl. This allows the software to be more contained and less dependent.
  • The remaining non-perl requires for the software to work are: gettext (for merging POT updates in to PO), java/FOP (for final stage of PDF), and rpmbuild (for srpm), Image Magick (svg->png)
  • If you are familiar with the 0.x versions of publican, you will notice that the Makefile content has moved to a perl-based publican.cfg file.
  • Books can have both a Makefile and a publican.cfg file. Having both these files allows books to be compatible with — and thus tested with — beta and shipped versions of publican.

Other Key Changes:

  • Syntax highlighting changed from xslthl (java-based syntax highlighting, approx 6 languages) to Syntax::Highlight::Engine::Kate, (approx 130 languages, see)
  • Translation languages (OTHER_LANGS) no longer need to be specified. Publican now uses directory parsing to calculate translations, using I18N::LangTags::List::is_decent
  • Creation of brands by a code-based solution. This allows generation of arbitrarily licensed brands, because all content is generated in code.
  • _Template directories completely removed from Brands in favour of a code-based solution. This allows the generation of arbitrarily licensed books.
  • Removed support for xalan, xsltproc and saxon. Xalan and saxon were used because xsltproc couldn't do column adjustments in table columnd or syntax highlighting. In the perl version, both column width and highlighting are supported.
  • Using XML::LibXML and XML::LibXSLT to manipulate and convert to output formats.
  • Using Module::Build for building (very cross-platform friendly) and Devel::Cover for testing. This should enable development of tests to ensure shipped packages are robust.

Participating in the Beta Program:

We are limiting participation in the initial Beta program to 6 members. This ensures that the developers can answer questions in a timely fashion. Those who want to participate will need to follow the documented procedures:

  1. be prepared to create a new book
  2. be prepared to migrate a book
  3. be prepared to migrate a translation stack
  4. be prepared to package a book
  5. be prepared to write 10 plain text regression tests on bugs in BZ

After the limited Beta, a wider Beta will ensue based on capacity. The publican-list@… email address will be used for communication.

Participants:

  1. Ruediger Landmann
  2. Jared Smith
  3. Amitakhya Phukan
  4. Darrin Mison
  5. Andrew Ross

Procedures

Installing the Software

  1. Fedora 11
    1. Download tarfile from Jeff's Fedora People Page
    2. Open a terminal
    3. Execute the following commands:
      tar zxf fedora-beta-fc11.tgz
      cd fedora-beta-fc11
      sudo yum --nogpg localinstall *.rpm
      
  2. Fedora 12
    1. Download tarfile from Jeff's Fedora People Page
    2. Open a terminal
    3. Execute the following commands:
      tar zxf fedora-beta-fc12.tgz
      cd fedora-beta-fc12
      sudo yum --nogpg localinstall *.rpm
      
  3. Ubuntu
    1. Download tarfile from Jeff's Fedora People Page
    2. Open a terminal
    3. Execute the following commands:
      tar zxf ubuntu-beta.tgz
      cd ubuntu-beta
      sudo dpkg --install --force-depends *.deb
      sudo apt-get install -f 
      
  4. Red Hat Enterprise Linux 5
    NOTE: Due to the number of dependencies this platform requires access to a Red Hat internal Yum repository.
    1. Ensure you have the internal yum repo enabled
    2. Download tarfile from Jeff's Fedora People Page
    3. Open a terminal
    4. Execute the following commands:
      tar zxf rhel5-beta.tgz
      cd rhel-beta
      sudo yum --nogpg localinstall *.rpm
      sudo yum install rpm -q perl-Locale-Maketext-Gettext
      
  5. Windows
    1. Download installer from Jeff's Fedora People Page
    2. Run Installer with Admin privileges
    3. Install all components
    4. Other Useful, but untested by us, Software
      1. SVN
      2. GIT
      3. GetText (manual install :( you need to download these and put them all in the same place)
        1. getext
        2. gettext tools
        3. libiconv
      4. FOP Requires java
    5. Known Issues
      1. After transforming XML to HTML publican crashes :( The content is generated correctly but libXML seems to have a problem cleaning up the result set :(
      2. Images used in installer are over sized
      3. Seems to fail on non US versions of Windows

Testing the Software

  1. Open a terminal
  2. publican --help
  3. Output should be:
    $ publican --help
    
    
    Usage:
        publican <global options>
    
        publican <action> <options>
    
        Global Options
    
            --help      Display help message
            --man               Display Full man page
            --help_actions      Display a list of valid actions
    
        Run: 'publican <action> --help' for details on action usage
    
        Valid actions are:
    
            build         Transform XML to other formats (pdf, html, html-single)
            clean         Remove all temporary files and directories
            clean_ids     Run clean ids for source XML
            cleanset      Remove local copies remote set books
            create        Create a new Book|Set|Article|brand
            create_brand  Create a new Brand
            help_config   Display help text for the configuration file
            installbrand  Install a brand to the supplied location
            old2new       Create a publican.cfg file for an old Book|Article|Set Makefile
            package       Package a language for shipping
            printtree     Print a tree of the xi:includes
            update_po     Update the PO files
            update_pot    Update the POT files
    

Creating a Beta test book

  1. Open terminal
  2. publican create --help
    $ publican create --help
    create
        Create a new Book|Set|Article
    
            Options:
            --name=<NAME>             The name of the Book|Article|Set|Brand
            --version=<VERSION>       The version of the product
            --edition=<EDITION>       The edition of the Book|Article|Set
            --product=<PRODUCT>       The name of the product
            --brand=<BRAND>           The brand to use
            --lang=<LANG>             The language the XML will be written in
            --type=<TYPE>             The type (Book|Article|Set)
    
    
  3. publican create --name=MyBook --lang=en-US --type=Book
  4. cd MyBook
  5. publican build --help
    $ publican build --help
    build
        Transform XML to other formats (pdf, html, html-single)
    
            Options:
            --formats=<FORMATS>       Comma separated list of formats. html,pdf,htm-single,html-desktop,text
            --langs=<LANGS>           Comma separated list of languages. e.g. en-US,de-DE,all
            --publish                 Setup built content for publishing
            --embedtoc                Embed the web site TOC object in the generated HTML
    
  6. publican build --formats=html,pdf --langs=en-US
  7. firefox tmp/en-US/html/index.html&
  8. evince tmp/en-US/pdf/MyBook.pdf&

Beta 0.x to 1.0 Migration Procedure

  1. Open terminal
  2. Pull down (F11 security guide)
    svn co http://svn.fedorahosted.org/svn/securityguide/community/fc11/ sec_guide_f11
    
  3. cd sec_guide_f11
  4. publican old2new
  5. vim publican.cfg (comment out brand with #)
  6. publican build --formats=html,pdf --langs=en-US
  7. firefox tmp/en-US/html/index.html&
  8. evince tmp/en-US/pdf/security-guide.pdf&

Beta 0.x to 1.0 Translation Stack Migration Procedure

  1. Open terminal
  2. Pull down (F11 installation guide)
    git clone git://git.fedorahosted.org/git/docs/readme-live-image.git
    
  3. cd readme-live-image
  4. publican old2new
  5. vim publican.cfg (comment out brand with #)
  6. publican build --formats=html,pdf --langs=hi-IN,ja-JP
  7. firefox tmp/hi-IN/html/index.html tmp/ja-JP/html/index.html&
  8. evince tmp/hi-IN/pdf/Fedora_Live_images.pdf tmp/ja-JP/pdf/Fedora_Live_images.pdf&

Testing Packaging

  1. Open a terminal
  2. cd to a Publican 1.x book
  3. publican package --help
    $ publican package --help
    package
        Package a language for shipping
    
            Options:
            --lang=<LANG>             The language the XML will be written in
            --desktop                 Create desktop instead of web package
            --brew                    Push SRPM to brew
            --scratch                 Use scratch instead of tag build.
            --short_sighted           Create package without using version in package name
            --binary                  Build binary RPM when running package
    
  4. run one or more of the following commands
    publican package --lang en-US
    publican package --lang en-US --desktop
    publican package --lang en-US --binary
    publican package --lang en-US --desktop --short_sighted --binary
    

Removing your beta installation

  1. Open a terminal
  2. remove package
    1. sudo yum remove Publican Publican-doc
    2. sudo apt-get purge Publican Publican-doc
  3. publican --help
  4. Output should be:
bash: publican: command not found

Frequently Asked Questions

Q: Can I use publican 0.x and Publican 1.0 concurrently?

A: Yes, but only during the beta program.

Q: What platforms should I be running for the beta program?

A: RHEL 5, Fedora 11/12, Ubuntu 8/9

Q: What about brands?

A: At this point, we will only be testing with the Common Brand. Once all regression tests and features and bugs have been addressed, there will be a separate event for branding.

Q: Why do I only get "Validation failed:" when I try to build my document? xmllint doesn't give me any errors.

A: Add a 'debug: 1' to your publican.cfg to get debug output for the error.


Feature Comparison

Output Formats

FormatCurrent 0.xNext Gen 1.xComment
html  
htmlhelp Never used, dropped
html-single  
html-desktop  
pdf  
txt Only known use in anaconda
eclipse Never used, dropped
test Didn't work like a format in 0.x

Build Targets

Build TargetCurrent 0.xNext Gen 1.xComment
[FORMAT]-[LANG]-[LOC] publican build --formats=html,pdf --langs=fr-FR,it-IT
[FORMAT]-all Dropped
brew-[LANG]-[LOC] publican package --desktop --brew --lang=en-US
brew-scratch -[LANG]-[LOC] publican package --desktop --brew --lang=en-US --scratch
brew-report-[LANG]-[LOC] Dropped, not used
clean publican clean
clean_ids publican clean_ids
clean_set_books publican cleanset
help publican --help | --man
help_params publican help_config
help_internals Dropped, unrequired
pom Dropped, unused
pre Dropped, not possible
publish-[FORMAT]-[LANG]-[LOC] publican build --publish --formats=html,pdf --langs=de-DE
publish-[FORMAT]-all Dropped
publish-report Dropped, unused
publish-web-[LANG]-[LOC] publican build --publish --embedtoc --formats=html,html-single --langs=en-US
report-[LANG]-[LOC] Dropped, statistics reported when PO updated
report-all Dropped
report-total-[LANG]-[LOC] Dropped
report-total-all Dropped
set_books Not directly callable, '''build''' handles this
spec-[LANG]-[LOC] Not directly callable, '''package''' handles this
srpm-[LANG]-[LOC] Not directly callable, package handles this
tar-[LANG]-[LOC] Not directly callable, package handles this
tardir-[LANG]-[LOC] Not directly callable, package handles this
test-[LANG]-[LOC] publican build --formats=test langs=en-US
test-all publican build --formats=test --langs=all
update_includes Dropped, never completed, never used
update-po-[LANG]-[LOC] publican update_po --langs=de-DE,fr-FR
update-po-all publican update_po --langs=all
update-pot publican update_pot
web-srpm-[LANG]-[LOC] publican package --lang=en-US
web-srpm-all Dropped
web-brew-[LANG]-[LOC] publican package --brew --lang=en-US
web-brew-scratch-[LANG]-[LOC] publican package --brew --lang=en-US --scratch
web-brew-report-[LANG]-[LOC] Dropped
xml-[LANG]-[LOC] publican --formats=xml --langs=fr-FR
xml-all publican --formats=xml --langs=all

Other Old Functions

FunctionCurrent 0.xNext Gen 1.xComment
rmImages Dropped, considered invasive
xlf2pot Dropped
po2xlf Dropped
create_book Integrated in to main executable: publican createbook ...
spell check Dropped, negative user feedback

New Actions

ActionCompleteComment
old2new Create a publican.cfg for a publican 0.x book
printtree Print a tree of the xi:include structure of a book.
package Build a tar, spec and srpm for a book or brand.
create_brand Create a brand from the command line.

Tested Operating Systems

OSCurrent 0.xNext Gen 1.xComment
RHEL 5  
Fedora  
Ubuntu  
Windows XP Tested using Active State Perl. Several packages were not in PPM repos and had to be hand-built. gettext & FOP not tested. Crash bug evident after LibXSLT is run, but valid HTML was generated.

Stand alone exe has been created and tested with HTML. Same tests as before, same results.