# LyXBlogger User Guide

## Jack Desert (jackdesert556@gmail.com)

Home
Download
Change Log
User Guide
Development Guide

Table of Contents

# 1The Basics

LyXBlogger (pronounced licks blogger) is a blog publishing tool. It doesn’t walk your dog, insult your mother, or assert world peace. But it does make composing and uploading blog entries simple and straightforward.
LyXBlogger (including this guide and all accompanying materials) is licensed under the GPL version 3 or, at your option, any later version. See the `LICENSE` file for details.
Please visit the main page to find out about the latest developments.

## 1.1 System Requirements--Client

The computer that LyXBlogger is installed on will be referred to as the client machine. This is likely the same computer that you use to compose your LyX documents and to convert them to xhtml.
Required:

- Python version between 2.4 and 2.6.[A] [A](Python 3.1 will be supported once the xmlrpclib module is ported to it.) Python 2.7.2 (full installs) seem to work on Windows, but Python 2.7.0 on Linux is still throwing errors for the developer.
- LyX
- A LyX -> xhtml converter (see 1.3↓)
- xterm (only required for GNU/Linux and Mac OSX, but they are generally already installed)

### 1.1.1Special Notes about Windows Installs

The popular way to install LyX on Windows is to use the binary installer available at http://www.lyx.org/Download. This will install Python onto your system, but it may not work with LyXBlogger. To check it out, open python by typing python at the command prompt.

    c:\>python
    Python 2.7.2 (default, Jun 12 2011, 15:08:59) [MSC v.1500 32 bit (Intel)] on win 32
    Type "help", "copyright", "credits" or "license" for more information.
    >>> import socket
    >>>

If it imports the socket module with no errors, your python installation is fine. If, however, you get an error

    ImportError: No module named _socket

Then you have a problem. The easy way around this is to rename your c:\Program Files\LyX20\Python directory to something like c:\Program Files\LyX20\Python_Renamed so that LyX won’t use that install. Then proceed to http://python.org/download/ and download and install the latest version of Python2.7. Open Control Panes -> Classic View ->System -> Advanced System Settings -> “Advanced” tab -> Environment Variables. Open the one called path and append ;c:\Python27 to the end of it (or wherever you installed Python. Then go on to 1.4↓ to install LyXBlogger. Once the LyXBlogger module is installed (under your new version of Python), reopen LyX, click Tools -> Reconfigure. Restart LyX, and if it’s LyX 2.0 or later, LyXBlogger will automatically show up in your export menu.

## 1.2System Requirements--Server

The computer that WordPress is installed on will be referred to as the server, since WordPress is often installed on a remote server.
Required:

- WordPress

WordPress can be installed on most web servers that support PhP and MySQL. Many web hosting companies even offer “one click install” of WordPress. For more information on installing WordPress on your site, see wordpress.org. Also check the documentation for your particular web server.
If you want to blog without the hassle of setting up the WordPress software yourself, you can sign up for a wordpress.com hosted blog. If you go this route, I recommend paying the small fee (about $10/year) for the ability to modify your own CSS file. That way you can customize the look and feel of your entries.

## 1.3 xhtml Converters

An xhtml converter is required as an intermediate step between LyX and your WordPress blog. You may use eLyXer, which comes bundled with LyXBlogger, or you may use LyX 2.0’s native LyXHTML converter.

## 1.4 Installation

First you will need to fetch the official distribution file from the download area. Start by uncompressing the distributed file to a suitable directory. Just write at the command prompt[B] [B]On Windows operating systems, right click on `LyXBlogger_[version].zip` and click Extract. .

    $ tar -xzf LyXBlogger_[version].tar.gz

A directory called `LyXBlogger_[version]` should appear.

    $ cd LyXBlogger_x.xx/
    $ cd INSTALL/
    $ python setup.py install

This default installation includes wordpresslib and eLyXer. To install without affecting your current eLyXer installation, you may use the alternate installer,

    $ python setup-no-elyxer.py install

## 1.5 Command-Line Usage

LyXBlogger is generally used from the export menu of LyX. (To set up your export menu, see section 1.10↓.) However, at its roots LyXBlogger is perfectly happy being called from the command line. To invoke LyXBlogger from the command line, first generate xhtml by previewing LyXHTML from LyX 2.0, or by either previewing or manually invoking eLyXer. Then change to the directory where the xhtml file resides. The location is shown in your browser window when you preview. Invoke LyXBlogger as

    $ python -m lyxblogger <input_file>

## 1.6 Test Drive

LyXBlogger comes out of the box ready to upload to a test site (blogtest.letseatalready.com) where you can test its posting capability. LyXBlogger will ask you whether to post to the test site or not. Once you can post to the test site, just run LyXBlogger again, this time telling it to use a different site instead. It will prompt you for your domain name, user name, and password.

## 1.7Profiles

New in version 0.38 is the ability to save several profiles. LyXBlogger comes out of the box with a profile called test@blogtest.letseatalready.com. Anyone may post to this blog. It’s for practicing. Then once you get the hang of how LyXBlogger works, add your own profile to the list and post to it.

## 1.8Password Prompt

The most secure method is to enter an empty password. This method does not save your password--you will be prompted to type it in each time you make a post.

## 1.9Image Uploads

HTML pages do not contain images, as PDF documents; rather they have pointers to image locations on disk. (Luckily LyX documents are the same in this respect.) LyXBlogger will find all the image tags in your xhtml document and upload them one by one to your blog site. Thus far JPG images have been tested.

## 1.10 LyX Integration

You may choose to use LyXBlogger solely from the command line. But it is often more convenient to set up LyXBlogger as a converter inside LyX so that you can just click a couple buttons when you are ready to upload your content. Then LyX automatically generates the xhtml for you using your selected xhtml converter, copies the xhtml file and any associated image files to a temporary directory, and uses those files when invoking LyXBlogger.

### 1.10.1LyXBlogger with LyX 1.6.x

If you used the standard installation of LyXBlogger, eLyXer is already installed on your system as a Python module. To set up LyX to use the eLyXer xhtml format when using LyXBlogger, use these standard options in your converter line:

    Converter: python -m elyxer --nofooter --directory $$r $$i $$o

For more information about eLyXer, see http://www.nongnu.org/elyxer/. Next you need to find out what your eLyXer output format is called in LyX. By default LyX calls it simply html. So as long as you haven’t changed it, that’s what it will still be called. Now go to Tools-> Preferences-> File Handling-> File Formats. Create a new file format. Give it a descriptive name like LyXBlogger (eLyXer)
Make sure you check Document Format.

    Short name: blog
    Extension: blog

Then click on Converters and define a new converter as follows: (This assumes that the format produced by eLyXer is still set to the default of "html")

    From_Format: HTML
    To_Format: LyXBlogger (eLyXer)
    Converter: python -m lyxblogger $$i

Now you can invoke this converter from within LyX by clicking File-> Export-> LyXBlogger (eLyXer)

### 1.10.2LyXBlogger with LyX 2.0.x

LyX 2.0 comes with LyXHTML support already built in. Once you have installed LyXBlogger, open LyX 2.0 and click Tools -> Reconfigure. Then restart LyX. LyX should have detected that LyXBlogger is installed and automatically set up the file format and converter for you. Click File -> Export-> LyXBlogger.
Using eLyXer with LyXBlogger and LyX 2.0
In LyX 2.0, LyXBlogger comes preconfigured to use the internal LyXHTML format. The other format supported is eLyXer xhtml format. If you used the standard installation of LyXBlogger, eLyXer is already installed on your system as a Python module. To use eLyXer instead of LyXHTML:

1. Open LyX 2.0 and go to Tools-> Preferences-> External Formats -> Converters.
2. Select the converter named LyXHTML to LyXBlogger.
3. Grab the From Format drop-down menu where LyXHTML is showing, and select HTML instead. (This assumes that your eLyXer format is still called HTML in LyX, which it is by default.)
4. Click Add and then Apply.
5. Highlight the original LyXHTML to LyXBlogger converter again.
6. Remove it by clicking Remove, and then Save.
7. Click Tools -> Reconfigure.
8. Restart LyX.
9. Run LyXBlogger again by clicking File -> Export -> LyXBlogger. When LyXBlogger opens it will tell you it is using the eLyXer format.

# 2Interface

## 2.1LyXBlogger

This is the welcome screen.

## 2.2Format

This explains which format was detected, and tells you what the other options are, so no format is left behind.

## 2.3Title

If you tag a line in your document as the title, LyXBlogger uses that as your posting title. If no title was detected, LyXBlogger will ask you to provide one.

## 2.4Cut Flag

Cut flag is a feature which allows you to put things end of your LyX document that will not be included in your post. That way, you don’t have to delete all your thoughts and musings from the document — you can keep them in your working copy without publishing them. If a cut flag is found, it will tell you so. If you thought you defind a cut flag, and it says it’s not found-- double check how you defined it to make sure your extra notes are not included in your post. The test site is good for trying this out, too, since if you make a mistake there, it’s not so obvious to the world. If you don’t get the cut flag right the first time, you can always re-post it later when you figure it out.
The default cut flag is defined in the USER DEFINED VARIABLES section of the code. :

    CUT_FLAG = ’#! CUT MATERIAL’

It’s what’s inside the single quotations that counts. So with the default cut flag, the next paragraph will be found as the cut flag.
#! CUT MATERIAL
See how the single quotes are gone? Note the single space between ’!’ and ’C’ and between ’T’ and ’M’? See how the cut flag is at the beginning of a paragraph? That will be picked up as a valid cut flag, and everything I write down here below it will not be posted. I can tell all the funny jokes I want down here and no one will ever read them.
If you want to change what is recognized as a cut flag, just edit lyxblogger.py and run

    python setup.py install

again from the INSTALL directory. On GNU/Linux this must be run as a super user.

## 2.5Domain

This asks you where you want to post to. The default is to the test site. If you type ’N’, you will be asked where you want to post to. If you want to change what site your LyXBlogger posts to by default, just edit lyxblogger.py and run

    python setup.py install

again from the INSTALL directory. On GNU/Linux this must be run as a super user.

## 2.6New or Existing

New means you’ve never posted this document before. Existing means you already posted this document, but now you’ve made a few changes to in and you want to replace the version that’s currently on the server with your latest changes. If you type ’E’ for Existing, you are provided with a short list of up to nine recent posts to choose from. If you are updating an existing post from further back than that, use the ’A’ option to bring in all your previous posts. This can take some time, depending on your internet connection. On fairly fast connection, with about 200 posts on the server, it takes my system about 30 seconds to bring these in.

## 2.7Category

The categories brought in are ones already set up in your blog. LyXBlogger is expecting a numerical input. If you type out the whole name of the title, if will ask to type it in again. To add additional categories to the list, log in to your wordpress site using your web browser and add them there. Then LyXBlogger can pick them up.

## 2.8Images

Before the post is published, each image in your LyX document is uploaded to the wordpres server. This may come as a surprise, but the bigger the image (in MegaBytes), the longer it takes to upload the image. The connectivity speed of your server plays a role here, as well. If it’s taking a long time, try posting to the test site at blogtest.letseatalready.com to compare upload speed.

## 2.9Words

Once any images are uploaded, the xhtml formatted text will be uploaded

## 2.10Success

This means you’re done. Note where it said your post was published to. Go to that address, and you’ll find your post.

# 3Advanced Use

There are some advanced uses for eLyXer if you want to extract the most of it.

## 3.1Delay

the DELAY parameter in USER_DEFINED_VARIABLES just puts a small pause in after the Copyright information displays. This gives the user a chance to read it. If you’ve already read it once, you can change it to

    DELAY = 0

## 3.2Capital or Lowercase

Anytime LyXBlogger asks for a response, such as ’Y’ for Yes, either an uppercase or lowercase response will do.

## 3.3What do the Parentheses Mean? (Y) N

This format means the one in parentheses will be selected if you press ENTER.

## 3.4Command Line Options

Running in Same Window
On GNU/Linux and Mac OS X, you can also run LyXBlogger without spawning a separate xterm window.

    $ python -m lyxblogger [source file] --run-here

## 3.5Unsupported eLyXer options

eLyXer has an option called --html. It causes eLyXer to output html instead of xhtml. Basically this means that it will not include closing tags. LyXBlogger is specifically looking for opening and closing tags in order to locate the title of your document. Therefore, the --html option is not supported.

## 3.6CSS

The look of your blog entries when you publish from LyXBlogger is entirely dependent on your CSS style file. If you are using eLyXer, a good starting place is to copy the eLyXer CSS file from http://www.nongnu.org/elyxer/lyx.css. It comes with sane defaults for getting your site going. Then you can tweak it as you go along to get a customized look.
If you are using LyXHTML format, you can build your own CSS style by first copying the embedded CSS styles. Just preview the LyXHTML, then from your browser click View-> Source Code. Copy all the CSS info to your own CSS file, and then edit to your liking. Since LyXHTML automatically wraps all paragraphs in an <a> tag, I recommend changing it so that each paragraph doesn’t underline itself when you mouseover it. This can be as simple as:

    a:hover{
        text-decoration: none;
    }

## 3.7Title

If a title is found in your LyX document, it will be used as your blog entry’s title. If one is not found, you will be prompted to enter one. By default eLyXer adds a title for you if you didn’t put one in. It is called “Converted Document”. This auto-generated title will be ignored, and you will be prompted for a proper title.
hat, but a planned extension will.

# 4Work in Progress

Work on LyXBlogger began in early 2010, has been gaining features as the months roll by. It’s still a work in progress, whose future depends largely on the tastes of those that use it. If you have suggestions for improving LyXBlogger, make them!

## 4.1Known Issues

Not running yet with Python 2.7 on Linux. Don’t know why. (Python 2.5, 2.6 work fine. Python 2.7.2 on Windows works fine.)

## 4.2Contact Information

If your problem does not appear in the above list, please let the author know; you can find him at JackDesert556@gmail.com. By doing so you can help the author improve LyXBlogger for future users. You can send your sample documents with a description of the errors encountered. Any documents sent will be treated with the utmost confidentiality.

# 5FAQ

Q:What versions of LyX, Python, and operating systems are supported?
A:It has been tested with LyX versions 1.6.4, 1.6.5, and 2.0.0. It has been tested with eLyXer version 0.41, 0.42, and 1.04. It has been tested with Python version 2.4 and 2.6. (Python 2.7.2 on Windows also works if it’s a full install, but Python 2.7.0 on Ubuntu is not working yet). It has been tested on Ubuntu 9.10, Mac OS X and Windows Vista 32-bit.
Q:There are indeed a ton of blogging clients over the web. Why add another one?
A:Because none of them allow composition from LyX.
Q:I don’t like how LyXBlogger outputs my document, what can I do?
A:First make sure that you are using an appropriate CSS file. i.e. copy the existing `docs/lyx.css` file to your blog’s server. Next try to customize the CSS file to your liking; it is a flexible approach that requires no code changes. Also consider trying both supported converters, as each one puts out somewhat different-looking output.
Q:Why are only LyXHTML and eLyXer formats supported?
A:Other formats were tested in the early development stages of LyXBlogger. Namely HeVea, TtH, and latex2html. Basically, it was simplest to find one or two formats that worked well and only support them. Perhaps future versions will support additional formats if users ask for it enough. Here is a rundown of features I liked and didn’t like about the formats I tried:
Supported:
LyXHTML: Good support for footnotes. Built in to future versions of LyX. Integration is simple.
eLyXer: Good support for footnotes. Very easy to get a working CSS file together which takes care of all usage scenarios.
Unsupported:
HeVeA Manages to insert a bunch of extra ’br’ tags into the html which makes the right edge all raggedy. And the numbered list issue is also that there’s an extra ’br’ tag inside the first item in each list, which looks weird.The four tools supported by LyX (tex4ht, HeVeA, TtH and latex2html) gave inferior results a couple of years ago, and were quite inflexible. The author found the need for a good converter, while at the same time acknowledging the difficulty of the problem.
LaTeX2Html This rendition is quite sophisticated, and it ultimately makes one little blog into a multiple page linked document. Nice for some things, but not what I was after.
TtH: Works quite well, and could be easily incorporated into LyXBlogger, but it does put footnotes at the bottom of the blog, where readers are unlikely to recognize them as footnotes.
Q:Why did you leave out my favorite feature <insert random LyX command here>?
A:In short, because nobody asked for it. Usually it is better to first aim for your own needs and what others request, and then worry about supporting everything, or you will never get anything done. Just let the author know what features you would like to see added.
Q:Is there a mailing list? I need help with installation / configuration.
A:Check out the lyxblogger-users mailing list.
Q:I found a bug, what should I do?
A:Just send it to the author at jackdesert556@gmail.com.
Q:Where did LyXBlogger start?
A:You can read about the initial work on LyXBlogger here, here, and here.
Q:How can I try out LyXBlogger without having to set up a WordPress blog?
A:Upload one of your documents to the LyXBlogger test site, which is what LyXBlogger will try to do anyway until you change this default behavior.
Q:Why does LyXBlogger take a long time to open when used with large documents?
A:Most of that time is waiting for the xhtml converter to run.
Q:Where can I get the latest documentation and information about LyXBlogger?
A:At http://www.nongnu.org/lyxblogger.