Permalink
Browse files

markdown: Improve documentation

* Add rst README file
* Add some useful screenshots
* Add a generated HTML help file
* Use the plugin_help() feature to load the HTML help file
* Update build system to install help files
  • Loading branch information...
1 parent 9be5443 commit 9fb81fcc2779c0fc28c6790c7ea0acda96ddd45d @codebrainz codebrainz committed Jul 16, 2012
View
@@ -16,5 +16,6 @@ AC_DEFUN([GP_CHECK_MARKDOWN],
markdown/Makefile
markdown/discount/Makefile
markdown/src/Makefile
+ markdown/docs/Makefile
])
])
View
@@ -1,4 +1,4 @@
include $(top_srcdir)/build/vars.auxfiles.mk
-SUBDIRS = discount src
+SUBDIRS = discount src docs
plugin = markdown
View
@@ -1 +1,174 @@
+Markdown
+========
+.. image:: plugin_small.png
+ :align: center
+ :alt: The Markdown plugin in action
+ :target: plugin.png
+
+.. contents::
+
+About
+-----
+
+This plugin provides a real-time preview of rendered Markdown, that is,
+`Markdown <http://daringfireball.net/projects/markdown>`_ converted to HTML
+and inserted into an HTML template and loaded into a
+`WebKit <http://www.webkit.org>`_ view.
+
+Features
+--------
+
+ * Allows placing the preview in the sidebar or message window areas
+ * Updates the preview on-the-fly as you type, automatically.
+ * Allows simple customization of fonts and colours and complete control
+ with custom template files.
+
+Usage
+-----
+
+The preview is active by default for all documents with a Markdown filetype
+set. To set a document's filetype, choose from the menus:
+
+.. image:: set_filetype.png
+ :align: center
+ :alt: Choosing Document->Set Filetype->Markup Languages->Markdown source file
+ :target: set_filetype.png
+
+Other than that the operation should be fully automatic. Use the Plugin
+Preferences mechanism to customize some settings as described below.
+
+For more information on Markdown syntax, read the
+`Markdown Syntax Documentation
+<http://daringfireball.net/projects/markdown/syntax>`_.
+
+*Preferences*
+^^^^^^^^^^^^^
+
+.. image:: settings.png
+ :align: center
+ :alt: The Markdown plugin's preferences GUI
+ :target: settings.png
+
+Using Geany's normal Plugin Preferences mechanism, you can customize some
+important settings related to the Markdown preview. The preferences dialog
+allows changing the following settings:
+
+========= ===================================================================
+Name Description
+========= ===================================================================
+Position The area of Geany's UI to put the preview view, currently either
+ in the sidebar or message window (bottom) areas.
+Font The regular body font of the preview.
+Code Font The font to use for the code tags (monospaced) font of the preview.
+BG Color The preview's background color.
+FG Color The preview's foreground (text) color.
+Template The file containing the HTML template for the preview.
+========= ===================================================================
+
+There's two ways to access the Plugin settings, one is through the
+Plugin Manager using the buttons highlighted below:
+
+.. image:: plugin_mgr.png
+ :align: center
+ :alt: The Plugin Manager dialog showing the Help and Preferences buttons.
+ :target: plugin_mgr.png
+
+Clicking the ``Help`` button opens this document in HTML format in your web
+browser. The other way to access the plugin's preferences is through the
+``Edit`` menu as pictured below:
+
+.. image:: plugin_prefs.png
+ :align: center
+ :alt: Accessing plugin preferences from the Edit menu.
+ :target: plugin_prefs.png
+
+*Custom Templates*
+^^^^^^^^^^^^^^^^^^
+
+You can provide a custom HTML template file which contains the substitution
+strings that get replaced at run-time. The following substitution strings
+are available:
+
+============================ ================================================
+Substitution String Description
+============================ ================================================
+``@@markdown@@`` The most important substitution string and
+ gets replaced with the HTML generated from the
+ editor's Markdown buffer. Not having this one
+ in the template makes the plugin completely
+ useless.
+``@@font_name@@`` The normal font family.
+``@@code_font_name@@`` The code/monospace font family.
+``@@font_point_size@@`` The size in points of the normal font.
+``@@code_font_point_size@@`` The size in points of the code/monospace font.
+``@@bg_color@@`` The background color in hex/HTML color notation.
+``@@fg_color@@`` The foreground (text) color in hex/HTML color
+ notation.
+============================ ================================================
+
+The default template file (at the time of writing) contains the following
+HTML code::
+
+ <html>
+ <head>
+ <style type="text/css">
+ body {
+ font-family: @@font_name@@;
+ font-size: @@font_point_size@@pt;
+ background-color: @@bg_color@@;
+ color: @@fg_color@@;
+ }
+ code {
+ font-family: @@code_font_name@@;
+ font-size: @@code_font_point_size@@pt;
+ }
+ </style>
+ </head>
+ <body>
+ @@markdown@@
+ </body>
+ </html>
+
+As you can see it's just normal HTML/CSS and you can tweak it to make the
+preview contents look exactly how you want. The preview view is a WebKit
+browser, the same one used by `Google's Chrome Browser
+<http://google.com/chrome>`_ and `Apple's Safari Browser
+<http://apple.com/safari>`_ as well as numerous others, and it supports many
+modern features such as HTML5 and CSS3 support (at least partially).
+
+If you mess up the default ``template.html`` file, just delete it and the
+default one will be recreated the next time the Markdown plugin is reloaded
+(for example when Geany restarts).
+
+Requirements
+------------
+
+The plugin depends on the following libraries:
+
+ * `GTK+ <http://www.gtk.org>`_ 2.16 or greater
+ * `WebKitGTK+ <http://webkitgtk.org>`_ 1.1.18 or greater
+
+License
+-------
+
+The Markdown plugin is licensed under the GNU General Public License,
+version 2 or (at your option) later versions. For the full text of the
+license, please visit http://www.gnu.org/licenses/gpl-2.0.html.
+
+Authors
+-------
+
+The Geany Markdown plugin is written and maintained by::
+
+ Matthew Brush <matt(at)geany(dot)org>
+
+The plugin includes the Discount Markdown library, developed by::
+
+ David Loren Parsons <http://www.pell.portland.or.us/~orc>
+
+Contact
+-------
+
+You can email me at ``matt(at)geany(dot)org``, or find me on the
+``#geany`` IRC channel on FreeNode, with the nickname ``codebrainz``.
View
@@ -0,0 +1,14 @@
+
+helpdir = $(docdir)/markdown/html
+help_DATA = \
+ help.html \
+ plugin.png \
+ plugin_mgr.png \
+ plugin_prefs.png \
+ plugin_small.png \
+ set_filetype.png \
+ settings.png
+
+# To update the HTML help file
+help.html: $(top_srcdir)/markdown/README
+ rst2html $< > $@
Oops, something went wrong.

0 comments on commit 9fb81fc

Please sign in to comment.