# LyXBlogger Developer Guide

## Jack Desert (jackdesert556@gmail.com)

Home
Download
Change Log
User Guide
Development Guide

Table of Contents

# 1The Basics

This document should help you get started if you want to understand how LyXBlogger works, and maybe extending its functionality. The package (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. Also visit the main page to find out about the latest developments.
In this first section we will outline how LyXBlogger performs the basic tasks. Next section will be devoted to more arcane matters. The third section deals with future planned extensions, and the fourth one includes things that will probably not be implemented. Finally there is a FAQ that contains answers to questions asked privately.

## 1.1Getting LyXBlogger

If you are interested in LyXBlogger from a developer perspective the first thing to do is fetch the code. It is included in the standard distribution, so just navigate to the `src/` folder and take a look at the `.py` Python code files.

# 2Advanced Features

## 2.1Unit Testing

Each file in src/LyxBlog/ has a file of unit tests to run.

## 2.2Running seed.py

If you want to debug LyXBlogger then it is better to run it from the source code folder, instead of the compiled version. For this you need to make just a small change, instead of `INSTALL/lyxblogger.py` run `src/seed.py`. On GNU/Linux or Mac OS X this file can be run as an executable like so:

    ./seed.py [input_file] --run-here

The --run-here flag prevents src/term.py from calling the lyxblogger module in an xterm window. This means that everything that’s executed will be done on local files, without the use of the lyxblogger module that may be installed on your system. This is much easier to develop on for most things.

## 2.3Interactive Testing

There is a test file in src/ called test_seed.py. This file calls all the unit tests, and then begins an interative test where seed.py will be invoked to talk to the server with automated responses given. Make sure you are connected to the internet when you run this test, or the test will appear to just run off the screen. If interactive_test.py is not working, first get seed.py to run with the ’--run-here’ option. Once seed.py is running with ’--run-here’, then go back to debugging interactive_test.py.
If the test you are working with is not finishing, comment out the other tests in interactivee_test.py so the test suite can finish and show you the results.

### 2.3.1print vs pr3

pr3 is used in LyXBlogger to enable messages to be passed back and forth between the interactive LyXBlogger and the interactive tester. Anything that must be passed to the interactive tester must use pr3. Anything else can use a regular print() statement.

### 2.3.2Unicode Strings

print() and pr3() don’t always play nicely with strings. This happens most often when using the interactive tester. Hence, some lines that are particularly problematic have been wrapped in a try: clause looking for a UnicodeEncodeError exception.

## 2.4Distribution

You will notice that in the `src/LyXBlog` folder there are several Python files, while in the INSTALL directory there is just a big one. The reason is that before distributing the source code is coalesced and placed on the main directory, so that users can run it without worrying about libraries, directories and the such. (They need of course to have Python 2.4, 2.5, or 2.6 installed.) And the weapon is a little Python script called `coalesce.py` that does the dirty job of parsing dependencies and inserting them into the main file. There is also a `make` Bash script that takes care of permissions and generates the documentation. Just type

> `$ ./distribute.py`

at the prompt. It is a primitive way perhaps to generate the “binary” (ok, not really a binary but a distributable Python file), but it works great. It also runs all of the included tests to check that no functionality has been lost from one release to the next — although some issues in a feature can slip undetected if there is no test for them.
./distribute.py also invokes test_seed.py to validate that all the tests are passing before creating the binary.
At the moment there is no way to do this packaging on non-Unix operating systems with a single script, e.g. a Windows `.bat` script. However the steps themselves are trivial.
If you are willing to send a patch to the LyXBlogger mailing list then you should patch against the proper sources in `src/` and submit that to the mailing list.

## 2.5License and Contributions

LyXBlogger is published under the GPL, version 3 or later [2]. This basically means that you can modify the code and distribute the result as desired, as long as you publish your modifications under the same license. But consult a lawyer if you want an authoritative opinion.
All contributions will be published under this same license, so if you send them this way you implicitly give your consent. An explicit license grant would be even better and may be required for larger contributions.

# 3Important Tidbits

## 3.1Calling Python Modules as Scripts

See this link on calling python modules as scripts with “python -m <module>” syntax.

## 3.2Testing a Release

Considerable unit testing and some interactive testing has been added to the code. But to ensure quality release code, the following tests are suggested before publishing a new release. Run then on GNU/Linux and on Windows:

- Upload a document with at least one picture and a title using eLyXer using AUTO_LOGIN
- Upload a document with at least one picture and a title using LyXHTML where you type in your url explicitly.
- Upload a document using eLyXer that has no title. Make sure it asks for a title and uses it.
- Upload a document using LyXHTML that has no title. Make sure it asks for a title and uses it.

# 4Future Extensions

The author has plans for the following extensions.

## 4.1Republish

The ability to correct changes in the original LyX file, publish the post, and have the new entry overwrite a previous entry instead of being posted as a new entry.

## 4.2Download and Edit Previous Entries

The author would love to have a bidirectional method in place for editing and republishing blog entries. The biggest question seems to be, “What converter will provide xhtml -> LyX conversion the best?”

## 4.3Display UTF-8 Titles

Correctly display UTF-8 titles on Windows machines. Works fine on GNU/Linux, but other characters show up on Windows. Either way, the entry is posted perfectly, it just looks funny in the LyXBlogger console window.

## 4.4Select Multiple Categories

The ability to select two or more categories for a single blog entry.

## 4.5GUI

A graphical user interface where the user can select previously posted blog entries, edit them, push the changes to the server.

## 4.6Page Creation

The ability to create a WordPress page.

# 5Roadmap

Who needs a map? A map would be nice, actually, but there isn’t one. Feel free to suggest one.

# 6Discarded Bits

Not everything that has been planned or can be done with LyXBlogger is planned; some extensions have been discarded. However, this means basically that the author is too ignorant to know how to do them right; help (and patches!) towards a sane implementation would be welcome if they fit with the design.

# 7FAQ

Q:I don’t like how LyXBlogger outputs my document, what can I do?
A:First make sure that you are using the proper 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. If all else fails, try changing the LyXBlogger code and submitting the patch back.
Q:Why does your Python code suck so much? You don’t make proper use of most features!
A:Because I’m mostly a novice with little Python culture. If you want to help it suck less, please send mail and enlighten me.
Q:I found a bug, what should I do?
A:Just report it directly to the main author.
Q:Where can I get the latest documentation and information about LyXBlogger?
A:At http://www.nongnu.org/lyxblogger.

# References

[1] Free Software Foundation, Inc.: LyXBlogger summary. https://savannah.nongnu.org/projects/lyxblogger/

[2] R S Stallman et al: “GNU GENERAL PUBLIC LICENSE” version 3, 20070629. http://www.gnu.org/copyleft/gpl.html

[3] S Chacon: “Git — Download”, accessed November 2009. http://git-scm.com/download

[4] Python community: “Download Python”, accessed November 2009. http://www.python.org/download/