• Read the Docs

    Apr 18, 2015

    Here’s something neat I found recently, while looking for some api docs. It’s been around for a while, but you might not have seen it if you don’t work with Python much.

    Check this out: https://readthedocs.org

    It’s a documentation repository, and you can find docs for a lot of Python projects there, in one searchable place. And you can host docs for your own project there, too.

    But what’s neat about it is you can author your docs in reStructuredText or Markdown, and have them built for online reading, or as an ePub or PDF for download. You can import docs from source control systems like git or subversion, and use hooks to automatically rebuild every time you push code.

    This is a pretty cool project with a lot of other features, and totally free, although you may want to help them out with a few bucks, too.

  • The FrameMaker Text Inset Header Problem

    Apr 15, 2015

    Here’s a FrameMaker thing that burns me once a year, usually a few hours before a release.

    So, you’ve done this:

    1. Created a text inset file that begins with a Head1 paragraph style.
    2. Inserted that file as a reference in another file, at a point where the paragraph style was Body.
    3. Did a book update, and a blank Head1 was magically added right after the inset, causing a blank entry in the TOC. Didn’t notice this until after the book went to QA and they asked why this keeps happening.
    4. Went to the file with the reference, changed it back to Body, regenerated.
    5. Repeated step 4 for an hour or two and ended up throwing your computer out of a window.

    Here’s how to get around it:

    1. Delete the reference in the file and start over.
    2. On the line where you add the inset, make that line consist of nothing but a single nonbreaking space (Ctrl-space).
    3. Move the cursor/insertion point to right BEFORE the nonbreaking space and do a File > Import to add the inset.

  • The Hello, World Post

    Apr 15, 2015

    Hi and welcome to my page. This is mostly a “blog about this insane little problem so I’ll remember it in a year,” but maybe some of these factoids will be useful to you, too.

    Click on any of the above to learn more about me. Or keep scrolling to see my current blog posts.

    Thanks,
    Jon