mirror of
https://github.com/gryf/.vim.git
synced 2025-12-18 12:00:30 +01:00
Added branch pathogen
This commit is contained in:
282
bundle/ft_vimblogger/doc/vimblogger_ft.txt
Normal file
282
bundle/ft_vimblogger/doc/vimblogger_ft.txt
Normal file
@@ -0,0 +1,282 @@
|
||||
*vimblogger_ft.txt* reStructuredText to Blogger interface
|
||||
Author: Roman Dobosz, gryf73 at gmail com
|
||||
|
||||
Simple interface to create blog articles in rsST format. It provides
|
||||
commands for preview in browser, post and delete articles.
|
||||
|
||||
-----------------------------------------------------------------------
|
||||
Requirements~
|
||||
|
||||
Module for communication was written in Python. So, VIm has to be
|
||||
compiled with +python.
|
||||
|
||||
Other requirements:
|
||||
|
||||
- Python (tested with version 2.6, should work also in others)
|
||||
- gdata http://code.google.com/p/gdata-python-client
|
||||
- docutils http://docutils.sourceforge.net
|
||||
- Pygments http://pygments.org (optional)
|
||||
- Blogger account
|
||||
|
||||
-----------------------------------------------------------------------
|
||||
Install~
|
||||
|
||||
Edit the vba file and type: >
|
||||
|
||||
:so %
|
||||
|
||||
========================================================================
|
||||
Usage~
|
||||
|
||||
This plugin is targeting for people, who has blogger account, want to
|
||||
use VIm for creating blog articles and don't really likes to manually do
|
||||
this in html.
|
||||
|
||||
Before starting writing a post, at least |g:blogger_name| and
|
||||
|g:blogger_login| has to be set up in |.vimrc|. Next, an article has to
|
||||
be written using standard reST markup, |:Title:| added (not required,
|
||||
but it's nice to have some title for a blog entry). Now,
|
||||
|:PreviewBlogArticle| can be used for saving generated HTML page into
|
||||
the file of the same name as reST file. Please note, that it'll silently
|
||||
overwrite existing file, because it is treated as a temporary file.
|
||||
|
||||
When article is done, |:SendBlogArticle| will send it to the server.
|
||||
|
||||
Output provided by |:PreviewBlogArticle| without any
|
||||
css stylesheet will look pretty raw, so it is generally good idea to
|
||||
grab stylesheets from blog itself, tweak it a little, and add to list
|
||||
in |g:blogger_stylesheets|. They will be automatically linked to
|
||||
generated preview file.
|
||||
|
||||
Unfortunately, this script has several limitations, like it is
|
||||
impossible to use multiple blogs or edit existing articles without reST
|
||||
source files. It has to be somehow converted to reStructuredText, id of
|
||||
an article added to |:Id:| docinfo item and then updated. Id of an
|
||||
article is available through blogger account - every action for each
|
||||
post listed on Posting->Edit Posts has URL with query string item
|
||||
postID, for example:
|
||||
|
||||
>
|
||||
http://www.blogger.com/post-edit.g?blogID=9876&postID=12345
|
||||
<
|
||||
|
||||
-----------------------------------------------------------------------
|
||||
Options~
|
||||
*g:blogger_browser*
|
||||
g:blogger_browser (default: 0)
|
||||
|
||||
If set to 1 output file from :PreviewBlogArticle will be opened in
|
||||
browser (used webbrowser Python module)
|
||||
|
||||
*g:blogger_name*
|
||||
g:blogger_name (default: "")
|
||||
|
||||
This is blog name, which is part of the URL, and user was obligated
|
||||
to enter it during blog creation. If in doubt, check first part od
|
||||
the URL of the blog, just after 'http://'. Note, that blog name may
|
||||
differ from the blog title, but also could be the same.
|
||||
|
||||
*g:blogger_login*
|
||||
g:blogger_login (default: "")
|
||||
|
||||
Google login name, usually gmail address.
|
||||
*g:blogger_pass*
|
||||
g:blogger_pass (default: "")
|
||||
|
||||
Password. If set to empty string, user will be asked for it every
|
||||
time if any blogger connectivity is performed.
|
||||
*g:blogger_draft*
|
||||
g:blogger_draft (default: 1)
|
||||
|
||||
By default, don't publish articles immediately, just save it on the
|
||||
service. If set to 0, article will be published.
|
||||
|
||||
*g:blogger_maxarticles*
|
||||
g:blogger_maxarticles (default: 0)
|
||||
|
||||
Number of displayed articles during deletion. 0 means all. Any
|
||||
positive number will display only that numbers of articles on list.
|
||||
|
||||
*g:blogger_confirm_del*
|
||||
g:blogger_confirm_del (default: 1)
|
||||
|
||||
Confirm every deletion. If set to 0, suppress the confirmation.
|
||||
|
||||
*g:blogger_stylesheets*
|
||||
g:blogger_stylesheets (default: [])
|
||||
|
||||
List of relative paths (relative to generated HTML document) of CSS
|
||||
stylesheets, used only for article preview in HTML document. Usually
|
||||
one wanted to save stylesheets from his own blog, so that article
|
||||
can be displayed almost in the same way as in blog.
|
||||
|
||||
*g:blogger_pygments_class*
|
||||
g:blogger_pygments_class (default: "")
|
||||
|
||||
Name of default CSS class for usage with Pygments. When not
|
||||
provided or empty, it'll use defaults from Pygments: "highlight".
|
||||
|
||||
========================================================================
|
||||
Commands~
|
||||
|
||||
*:PreviewBlogArticle*
|
||||
|
||||
Generate article in HTML format, save it to the file with te same
|
||||
name as a reST source with .html extension in the same directory,
|
||||
and optionally opens it in browser. No connection to the blogger is
|
||||
performed.
|
||||
|
||||
*:SendBlogArticle*
|
||||
|
||||
Generate partial HTML document, which holds article, from current
|
||||
reST buffer and send it to the blog.
|
||||
|
||||
See reST document structure below for further description.
|
||||
|
||||
*:DeleteBlogArticle*
|
||||
|
||||
Display list of articles, and lets user choose one (or none) of them
|
||||
to perform deletions.
|
||||
|
||||
========================================================================
|
||||
reST document structure~
|
||||
|
||||
It is assumed, that following template will be used:
|
||||
>
|
||||
:Id:
|
||||
:Title: Title for the blog article
|
||||
:Date:
|
||||
:Modified:
|
||||
:Tags: some, tags
|
||||
|
||||
Penatibus et magnis dis parturient montes, nascetur ridiculus mus.
|
||||
Nulla facilisis massa ut massa. Sed nisi purus, malesuada eu, porta
|
||||
vulputate, suscipit auctor, nunc. Vestibulum convallis, augue eu luctus
|
||||
malesuada, mi ante mattis odio, ac venenatis neque sem vitae nisi.
|
||||
|
||||
.. more
|
||||
|
||||
|
||||
heading
|
||||
-------
|
||||
|
||||
**Congue** mi, quis posuere augue nulla a augue. Pellentesque sed est.
|
||||
Mauris cursus urna id lectus. Integer dignissim feugiat eros. Sed
|
||||
tempor volutpat dolor. Vestibulum vel lectus nec mauris semper
|
||||
adipiscing.
|
||||
|
||||
Aliquam tincidunt enim sit amet tellus. Sed mauris nulla, semper
|
||||
tincidunt, luctus a, sodales eget, leo. Sed ligula augue, cursus et.
|
||||
<
|
||||
reST document (optionally) starts with *docinfo* section (first several
|
||||
lines, that are starting from ":" character) separaded from other
|
||||
content with one empty line.
|
||||
|
||||
Docinfo items holds article attributes, and are updated automatically
|
||||
every each of upload to blogger, which is triggered by
|
||||
":SendBlogArticle" command.
|
||||
|
||||
*:Id:*
|
||||
Holds article id on blogger side. If not defined, new article will
|
||||
be created (even if there is already existing one with the very same
|
||||
content). If wrong Id is entered (or an Id of deleted article),
|
||||
exception will be raised, and no action on blogger side will be
|
||||
performed.
|
||||
|
||||
*:Title:*
|
||||
Holds article title. Can be changed when |:Id:| is obtained.
|
||||
|
||||
*:Date:*
|
||||
This is published date in RFC 3339
|
||||
http://www.ietf.org/rfc/rfc3339.txt format. If empty on first
|
||||
upload, it will be set to current date. Can be set/changed to
|
||||
desired date.
|
||||
|
||||
*:Modified:*
|
||||
This is read-only item, which store modification date which happens
|
||||
on blogger side.
|
||||
|
||||
*:Tags:*
|
||||
Comma separated list of tags (Labels). Can be empty.
|
||||
|
||||
All other items are ignored.
|
||||
|
||||
After docinfo block, article body should be placed using markup for
|
||||
reStructuredText.
|
||||
|
||||
Note, that `.. more' will became HTML comment `<!-- more -->' which will
|
||||
prevent from displaying entire post on the bloggers front page, but will
|
||||
not have any visible effect during preview in browser.
|
||||
|
||||
========================================================================
|
||||
Pygments code highlighting~
|
||||
|
||||
Additionally, if Pygments is installed, there is ``sourcecode``
|
||||
directive, simple syntax highlighter using Pygments module. Very simple
|
||||
usage for Python code could be as follows:
|
||||
>
|
||||
.. sourcecode:: python
|
||||
|
||||
import vim
|
||||
print vim.current.buffer.name
|
||||
<
|
||||
Note, that `sourcecode' directive requires argument with the name of the
|
||||
lexer to use. If wrong/non existent lexer is provided, it will fall back
|
||||
to `text' lexer. For more information about available lexers, please
|
||||
refer to Pygments documentation.
|
||||
|
||||
Directive `sourcecode' supports two options: `:linenos:' and
|
||||
`:cssclass:'.
|
||||
|
||||
`:linenos:' takes zero or one argument - if no arguments is provided,
|
||||
line numbers will be visible starting form 1. Provided integer will be
|
||||
the number of the first line.
|
||||
|
||||
`:cssclass:' can be use for changing default class name for block of
|
||||
code. Default class can be changed by appropriate option for plugin
|
||||
(see documentation), and defaults to "highlight".
|
||||
|
||||
It is possible to use VIm colorschemes like desert (which is distributed
|
||||
with VIm), Zenburn, Lucius, Wombat, inkpot or any other with Pygments.
|
||||
Assuming, that colorscheme `desert' should be used, there are two steps
|
||||
to achive it.
|
||||
|
||||
First, python module containing Pygments `Style' class has to be
|
||||
generated. There is appropriate conversion tool in Pygments
|
||||
distribution - `scripts/vim2pygments.py'. Uage is simple as:
|
||||
>
|
||||
python Pygments/scripts/vim2pygments.py \
|
||||
path/to/vim/colors/desert.vim > desert.py
|
||||
<
|
||||
Which will create new python module ``desert.py`` containing class
|
||||
`DessertStyle`'.
|
||||
|
||||
To generate CSS stylesheet, it's enough to:
|
||||
>
|
||||
python rst2blogger/scripts/style2css.py desert.py \
|
||||
-c VimDesert > desert.css
|
||||
<
|
||||
VimDesert is the name of the class, which passed as an argument to
|
||||
`:cssclass:' option of directive `sourceocode'. It will be used as a
|
||||
main CSS class for code top `<div>' element. So, above example will
|
||||
looks like this:
|
||||
>
|
||||
.. sourcecode:: python
|
||||
:cssclass: VimDesert
|
||||
|
||||
import vim
|
||||
print vim.current.buffer.name
|
||||
<
|
||||
Note: All headings for generated HTML by |:SendBlogArticle| will be
|
||||
shifted by 3, so the first heading will become <h3>, second <h4> and so
|
||||
on, to fit into blogger template (well, most of them). Remember, that
|
||||
HTML allow up to 6 level of headings, while reST doesn't have this
|
||||
limitation.
|
||||
|
||||
========================================================================
|
||||
Changelog~
|
||||
|
||||
0.2 Pygments sourcecode directive improvements
|
||||
0.1 First release
|
||||
|
||||
vim:tw=72:fo=tcq2:isk=!-~,^*,^|,^":ts=8:ft=help:norl:
|
||||
Reference in New Issue
Block a user