Idiotprogrammer Blog

Category: Python/Zope/Plone

  • Docbook, Pandoc, Rants and Some Decent Free Fonts

    I’m working on a user manual and am in the process of discovering several tools to do the job.

    Here’s RSTA,  an online restructured text editor which lets you output into HTML and PDF. This is mainly of interest to people in the plone and python world.

    Python programmer extraordinaire Mark Pilgrim explains why he codes in HTML and not Docbook. From the comment section, I learn about Pandoc, a great program for converting different forms (LaTex, RST, markdown, HTML, Docbook, gosh – just about everything!).

    Here’s the Pandoc user guide and an online converter. The key, I’m guessing is how it handles unicode and document fragments, but I look forward to finding this out.

    Pilgrim also does a rant about the restrictive fonts:

    I know what you’re going to say. I can hear it in my head already. It sounds like the voice of the comic book guy from The Simpsons. You’re going to say, “Typography is by professionals, for professionals. Free fonts are worth less than you pay for them. They don’t have good hinting. They don’t come in different weights. They don’t have anything near complete Unicode coverage. They don’t, they don’t, they don’t…”

    And you’re right. You’re absolutely, completely, totally, 100% right. “Your Fonts” are professionally designed, traditionally licensed, aggressively marketed, and bought by professional designers who know a professional typeface when they see it. “Our Fonts” are nothing more than toys, and I’m the guy showing up at the Philadelphia Orchestra auditions with a tin drum and a kazoo. “Ha ha, look at the freetard with his little toy fonts, that he wants to put on his little toy web page, where they can be seen by 2 billion people ha h… wait, what?”

    Let me put it another way. Your Fonts are superior to Our Fonts in every conceivable way, except one:

    WE CAN’T FUCKING USE THEM!

    Soon — and I mean really fucking soon, like “this year” soon — there will be enough different browsers in the hands of enough different people that can use any possible font on any possible web page. And then a whole lotta people will start noticing fonts again — not just Your People, just also Our People. People who couldn’t tell a serif from a hole in their head, but they’re gonna be looking for new fonts. People who are just savvy enough to be tired of Comic Sans will be looking for a new font to “spruce up” their elementary school newsletter, which, in an effort to Love Our Mother (Earth), they now publish exclusively online.

    A typeface designer responds:

    As a type designer I feel like I have to step in and say something here. First off the majority of typefaces designed in the past twenty years haven’t been made by big foundries but by individuals working on type in their spare time. Second, typefaces receive no copyright protection in the United States so copying font files and renaming them for sale is pretty much legal. Third, fonts have been available on peer-to-peer networks since before the days of Napster and in 2000 it was estimated that only one out of fifty instances of a typeface file (postscript or TrueType files) was paid for, and it has only gotten worse.

    I have over forty commercial typefaces available for sale through various type re-sellers around the world and my average yearly income off the typefaces is $115, even though I regularly see my typefaces in use on the web, on TV in print and in video games. I used to think that one day I’d have a nice supplemental income from my typefaces but the reality of the situation is that people like you don’t value the effort that goes into making a typeface. I haven’t designed a new typeface in eight years now and I have no desire to do so. Why should I when you’re going to be a big bitching twat you greedy self-centered tantrum throwing teenager?

    Actually, the whole thread has a lot of expletives and rants, but lots of issues come up.  Actually, the most valuable information I gleaned from the threads were the names of some decent free fonts: Gentium, Day Roman, Yanone Kaffeesatz, Yanone Tagesschrift, Delicious, Aller, Charis SIL, Doulos SIL, Junicode,  Linux Libertine, the Liberation and Droid families, and Computer Modern (or, more likely, its Type 1 version, Latin Modern).

    See also the Open Font library (here’s the beta version, which seems buggy—the search results only gives 1 result). Here’s a general list of the most famous free fonts, separated by license type.

    Here’s a good (and indispensable) article about how to use the font-face css rule to use any of these awesome free fonts. Here’s another how-to. Here’s a nice demo.

    Update: This browser support table shows that Chrome 3 (the current version) does not support embedded fonts, and that Chrome 4 will be released in 2010. Also, Internet Explorer only supports EOT fonts. (I’m not 100% sure what that means; according to the link in the previous paragraph, EOT is a Microsoft implementation of fonts. Certainly there has to be a conversion tool? Update 2: this font wiki has this information and more).

    The free font issue is important for distributing ebooks. (Here’s a mobileread discussion). The .epub standard supports embedded fonts (I think), and having a unique font makes reading a more enjoyable experience when reading on a  Kindle or Nook.  I am growing weary of the same font on my Sony PRS 505 reader.

    I guess I haven’t mentioned it yet, but I’m working on two creative commons ebooks and am working on a user guide to publish on Booksurge and possibly as an ebook as well. For that reason, I’ve been learning a LOT about docbook. Overall, I’m happy with its flexibility even though the learning curve was steep –and also I’m depending a little too much on a on a noncommercial license of Oxygen XML editor. If I wanted to do something commercial, I’d have to pay $349 for a full version and $199 for an Author version (which lacks some  XML/XSLT tools but has an easier interface). Frankly, Oxygen is incredible, but I’m close to making commercial use of it.

    Serna XML editor (the free version) is good for authoring, but I haven’t figured out how to validate it using various  schemas and DTDs. Apparently, Serna uses python plugins to enable validation of various XML languages like docbook and DITA. It looks like Serna only supports 4x versions of Docbook; I could be wrong.

    By the way, after I finish one or two ebook projects, I plan to write an article about using docbook for ebook creation.

  • Book Review: Practical Plone 3

    With the proliferation of content management system (CMS) software, a need has arisen for good manuals. When a CMS starts out, user forums are usually the main place for help;  then someone will start a wiki, and a few people will write tutorials on their blogs. But if the user base for a CMS grows rapidly, docs quickly go out of date, and it becomes hard to figure out which parts of the docs still apply for the latest release.  That poses a risk for someone wishing to buy  a technical book (or  write  one).  Technical publishers use several methods to future-proof their books. This includes: focusing on core features unlikely to change between releases, anticipating future development, publishing smaller books that require less time to produce and group writing. Group writing (assigning different people to contribute chapters) has been a popular method because it reduces the burden on one person. As long as the assigned topics don’t overlap and are well organized, group-written technical books can be extraordinarily helpful and can be released quickly, as in the case of  Packt Publishing’s latest Plone book (Practical Plone 3).

    First, a little background. Plone is a python-based CMS that has a large user base and many enterprise  features. It is deployed on many nonprofits and governmental sites and historically has been easier to secure than LAMP CMS’s like Drupal. Data is stored in an object database (ZODB)  as opposed to relational databases (although adapters have been written to connect to mysql, postgresql, etc).   Plone is based on a platform called Zope, and in fact Plone’s version 3  release in 2007 implemented many architectural changes.
    Packt has published several Plone books already (including Martin Aspelli’s well-regarded 2007 book Professional Plone Development), and the latest book is bigger, covers more topics and should interest a wider audience.  

    About half of the pages (and a third of the chapters) in this 565 page book contain screenshots to demonstrate functionality which can be controlled with the web interface. However, the book’s audience is not really for novice users or content creators (despite the book’s subtitle that is a "beginner’s guide"). If you wish for something like that, try  the excellent Users Guide to Plone —downloadable for free). Practical Plone 3 covers basic topics in Chapters 4-6, but it focuses on several  topics which are not easy to find the answers for. This book would be useful for the website administrator or the developer or designer trying to customize Plone for an organization or company.

    First, Plone includes lots of features not enabled by default which are hidden in the administration menu (called "Plone Site Setup"). Unlike Drupal (which seems to have a massively complex control panel), Plone Site Setup looks deceptively simple, but lots of things are hidden under the hood. So you need to know where to look.   Practical Plone 3 explains how to use a lot of these features:  versioning, managing groups and roles, creating custom workflows and using the portlet manager to control what sidebars appear on the left or right of the web page.

    Plone differs in many ways from LAMP CMSs both in architecture and concepts. Usually, these differences remain hidden from users. But  understanding these  differences can help you  understand why things work differently in Plone. For example, Plone uses the folder-file metaphor for content objects. They can have states and properties; they can be copied/cut/pasted into other Plone folders even though they don’t really exist as files or folders on the file system itself. Another easily overlooked feature is the extensive metadata fields that exist for content types. (it exists in a secondary horizontal tab  like this one ).

    The book chooses (wisely) not to talk too much about third party Plone  products (i.e., plugins). But it does go into great detail about using PloneFormGen (an auto-generator of web forms) and cache-fu (an indispensable product for caching performance). These two sections were very well done.

    The last half of the book describes  how Plone development proceeds, beginning with creating  new content types. In Chapter 16, the book covers how to use a graphical UML tool called ArchGenXML to create a new content type based on the builtin content types. Here you use Archetypes, a Plone-specific way of building content types. (Archetypes have been around since Plone 2). After you use the graphical tool to create UML, the ArchGenXML script will generate the product code for you to upload to the server’s file system.  Later, in Chapter 17, there is a good walkthrough of using Generic Setup to export configuration changes you make in the Zope Management Interface (ZMI) into an XML file on the file system.  That allows you  to replicate site configuration more easily and  keep configuration information outside of the database.   Chapter 17 also  covers the Zope 3 architecture underlying Plone and how to set up browser views in ZCML configuration files and viewlets and portlets.

    Chapter 18 covers the creation of themes and css for a Plone site. This process is slightly complicated because you make your changes to a themed product which is later installed/enabled from Plone Site Setup. The book walks you through the steps of using a python script called paster to generate a series of files which make up the theme product. Editing the css for the theme is possible only if you understand how viewlets work and which files you are supposed to edit (it is not simply a styles.css file).

    The last two chapters cover caching and performance tuning. Overall, well done.

    In general, this is an excellent guide and it covers a lot of ground thoroughly. Unlike the Drupal series of books by Packt (which struck me as flimsy–they have 12 separate books!), this book  combines  all the important aspects of Plone 3 into  a single book.  Everything in the book struck me as important–none of the material seemed like padding. The usage information in the first section was very well done (although it probably needed better coverage of Kupu, the rich text editor).  The section on workflows was great, and the explanation about Zope 3 views seemed well done, but the look-and-feel chapter looked imposing. If editing a CSS class means having to edit a theme product and re-add it, that might discourage doing too many tweaks (especially on a live site!). It would have been nice to have an appendix summarizing the configuration files, location of important objects in the ZMI and CSS classes.   I did not see any chapter  about uploading images or multimedia files on the file system; that seemed to be outside of the book’s scope.   I am not a developer (I just play one on TV), but there seemed enough meat in the advanced sections to address many contexts.

    Finally, it’s worth pointing out that the plone.org site has a well-organized documentation section. The book may lack a good section on kupu, but plone.org has  several help topics about Kupu.  (In fact, many of the book’s contributors also produce documentation for the Plone.org site). One doesn’t read this kind of book for narrative; nonetheless,  most of it was easy to read and easy on the eyes.  Except for chapters 17 and 18 (which were a little deep), the rest of the book got straight to the point quickly.

    In summary: this book is a substantial guide which covers a lot of intermediate and advanced topics. Very well written and organized (with lots of illustrations), but the section on themes was hairy and even a little confusing

    *******

    Robert Nagle is a technical writer and fiction writer who lives in Houston.  He blogs about culture and technology on his idiotprogrammer weblog.

  • Ploneability Higher Education Workshop: November 7

    I’ll probably be attending the Ploneability Higher Education workshop at University of Houston on November 7.  Registration is free.

    I don’t work at a university per se, but my plone/ebook implementation should be relevant to people at the university.  Plus, I used to teach at a university in another life.

  • Plone 3 is released!

    Plone 3 is released. Lots of new features here. I’ll be spending the next two weeks working rather building out a plone 3 site for a new project. All I’ll say is, About Fu**ing Time! (Honestly, these are tears of joy)…

  • Houston Zope Python User Group (Houzpug)

    Here. It looks like Houston Zope Python User Group has a website (actually just a redirect). Let’s see how much google juice getting blogged about here gives the site.