LyXBlogger User Guide

Jack Desert (jackdesert556@gmail.com)

1 The 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

LyXBlogger requires Python 2.4.x - 2.6.x. [A→] [→A] (Python 3.1 will be supported as soon as the xmlrpclib module is ported to it.) It will publish documents created by eLyXer and by LyXHTML. It has been tested on the most common operating systems: on Mac OS X, Linux and Windows.
On GNU/Linux and Mac OS X systems, xterm is required in order to produce the external window that displays messages and asks for user input. The systems I tested on had this installed by default anyway.
A WordPress blog site is required. You can get one at wordpress.com, but make sure you pay the small fee to get the right to edit your CSS file. That way you can customize the look and feel of your entries. Or you can install wordpress on your own MySQL-enabled web server.

1.2 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:
$ tar -xzf LyXBlogger_[version].tar.gz
Or for the .zip version:
$ unzip LyXBlogger_[version].zip
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.3 xhtml Converters

An xhtml converter is also required. You may use eLyXer, which comes bundled with LyXBlogger, or you may use LyX 2.0’s native LyXHTML converter.
To invoke LyXBlogger, first generate xhtml by previewing LyXHTML from LyX 2.0, or by either previewing or manually invoking eLyXer. Then cd to the directory where the (x)html files and images reside The location is shown in your browser window when you preview. Invoke LyXBlogger as
$ python -m lyxblogger input_file

1.4 Usage

LyXBlogger is a standalone command line tool. It can be invoked from the command line as:
$ python -m lyxblogger [source file] 
LyXBlogger will assume that if your source file ends in .html, that it is in eLyXer format. And if it ends in .xhtml, it will assume it is in LyXHTML format.

1.5 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.6 Auto Log In

To facilitate automatic login to your own site, just change the following lines in the USER DEFINED VARIABLES section of LyXBlogger_x.xx/INSTALL/lyxblogger.py:
AUTO_URL = ’http://blogtest.letseatalready.com/xmlrpc.php’ 
AUTO_USER = ’test’ 
AUTO_PASSWORD = ’test’ 
AUTO_LOGIN = True
Simply put your own domain in place of blogtest.letseatalready.com, leaving the http:// and the /xmlrpc.php parts intact. Make sure you change AUTO_USER to your WordPress user name and AUTO_PASSWORD to your WordPress password. Save lyxblogger.py and reinstall it:
$ cd LyXBlogger_x.xx/ 
$ cd INSTALL/ 
$ python setup.py install 

1.7 Image 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.8 LyX Integration

You may choose to use LyXBlogger solely from the command line. But it is often more conventient 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.8.1 LyXBlogger 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 --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 caleld. 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.8.2 LyXBlogger 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.

1.8.3 Manual Integration

If for some reason the auto configuration is not working for you, or if you have renamed you eLyXer format to something other than HTML, you may need to configure your convertersettings manually.
Select theFile Handling-> File Formats. Create a new file format. Give it a descriptive name like LyXBlogger or 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: [The name of your LyXHTML or eLyXer output] 
To_Format: [The name of your blog format]
Converter: python -m lyxblogger $$i
Note that at this time only LyXHTML and eLyXer xhtml formats are supported by LyXBlogger.

2 Advanced Use

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

2.1 Command 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

2.2 Unsupported 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.

2.3 CSS

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 eac paragraph doesn’t underline itself when you mouseover it. This can be as simple as:
a:hover{
    text-decoration: none;
}

2.4 Title

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.

3 Work in Progress

Work on LyXBlogger began in early 2010, and is still very much a work in progress.

3.1 Known Issues

The following issues (including bugs and missing features) are acknowledged. Some of them should be solved soon; others may take longer.
Multiple Categories:Currently LyXBlogger only supports selecting a single category per entry. This is an easy fix, but has not been implemented yet.
Editing Previously Published Blogs:Currently LyXBlogger is a unidirectional blog posting machine. Perhaps in the future it will support downloading a previously posted blog, converting it to LyX Format, and allowing reposting after editing.

3.2 Contact 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.

4 FAQ

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 and 0.42. It has been tested with Python version 2.4 and 2.6. 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: 
HeVeAManages 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.
LaTeX2HtmlThis 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: 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: Where can I get the latest documentation and information about LyXBlogger?
A: At http://www.nongnu.org/lyxblogger.

Copyright (C) 2010 Jack Desert (jackdesert556@gmail.com)