LyXBlogger User Guide
Jack Desert (jackdesert@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--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.7.
-
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.1 Special 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 sometimes this version of Python does not work with LyXBlogger. To find 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.
>>>
Then type ’import socket’ at the python prompt
>>> 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.2 System 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 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.
$ 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
You can verify that LyXBlogger is installed by calling it from the command line in the next section.
1.5 Command-Line Usage
LyXBlogger can be invoked from the command line as follows:
$ python -m lyxblogger <input_file>
Where <input_file> is an html file that was generated by either eLyXer or LyX 2.x. If you don’t have such an input file handy, you can use this one from the LyXBlogger download:
$ python -m lyxblogger lyxblogger/src/LyxBlog/test_files/lyxhtml_w_images/LyXHtml_test_with_image.xhtml
Once LyXBlogger is working from the command line, you can go on to integrate it into the LyX export menu (see section
1.9↓.)
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.7 Password Prompt
When adding a new profile, 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.8 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.9 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 calls LyXBlogger on those files.
1.9.1 LyXBlogger with LyX 2.0.x
LyX 2.0 has its own html converter built right in, called LyXHTML. 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-> More Formats and Options -> LyXBlogger.
Using an Alternate Html Converter with 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:
-
Open LyX 2.0 and go to Tools-> Preferences-> External Formats -> Converters.
-
Select the converter named LyXHTML to LyXBlogger.
-
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.)
-
Click Add and then Apply.
-
Highlight the original LyXHTML to LyXBlogger converter again.
-
Remove it by clicking Remove, and then Save.
-
Click Tools -> Reconfigure.
-
Restart LyX.
-
Run LyXBlogger again by clicking File -> Export -> LyXBlogger. When LyXBlogger opens it will tell you it is using the eLyXer format.
1.9.2 LyXBlogger with LyX 1.6.x
LyX 1.6.x does not come with any html converters. However, the standard installation of LyXBlogger will install the eLyXer converter 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)
2 Interface
2.1 LyXBlogger
This is the welcome screen.
2.2 Format
This explains which format was detected, and tells you what the other options are, so no format is left behind.
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.4 Cut 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.5 Domain
This asks you where you want to post to. The default is to the test site. If you type ’N’ for ’New’, you will be asked for a different domain to post to.
2.6 New 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.7 Category
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.8 Images
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.
Once any images are uploaded, the xhtml formatted text will be uploaded
This means you’re done. Note where it said your post was published to. Go to that address, and you’ll find your post.
3 Advanced Use
There are some advanced uses for eLyXer if you want to extract the most of it.
the DELAY parameter in USER_DEFINED_VARIABLES section of lyxblogger.py 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
and reinstall LyXBlogger.
3.2 Capital or Lowercase
Anytime LyXBlogger asks for a response, such as ’Y’ for Yes, either an uppercase or lowercase response will do.
3.3 What do the Parentheses Mean? (Y) N
This format means the one in parentheses will be selected if you press ENTER.
3.4 Command Line Options: running from same window
On GNU/Linux and Mac OS X, you can also run LyXBlogger without spawning a separate xterm window by adding the ’--run-here’ flag.
$ python -m lyxblogger [source file] --run-here
3.5 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.
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;
}
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.
4 Support & Contact Information
If you have any trouble getting LyXBlogger up and running, or if you have suggestions for cool new features, or ACK! a bug report, please write to
lyxblogger-users@nongnu.org. Alternately, you can reach the author directly at
JackDesert@gmail.com.
5 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, 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: I found a bug, what should I do?
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?