LyXBlogger Developer Guide
Jack Desert (jackdesert@gmail.com)
1 The 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.1 Getting 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.
2 Advanced Features
2.1 Unit Testing
Each file in src/LyxBlog/ has a file of unit tests to run.
2.2 Running 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.3 Interactive 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.1 print 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.2 Unicode 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.4 Distribution
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.5 License 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.
3 Important Tidbits
3.1 Calling Python Modules as Scripts
See
this link on calling python modules as scripts with “python -m <module>” syntax.
3.2 Testing 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.
4 Future Extensions
The author has plans for the following extensions.
4.1 Republish
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.2 Download 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.3 Display 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.4 Select Multiple Categories
The ability to select two or more categories for a single blog entry.
A graphical user interface where the user can select previously posted blog entries, edit them, push the changes to the server.
4.6 Page Creation
The ability to create a WordPress page.
5 Roadmap
Who needs a map? A map would be nice, actually, but there isn’t one. Feel free to suggest one.
6 Discarded 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.
7 FAQ
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?
Q: Where can I get the latest documentation and information about 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/