Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

merge idea.rst and about.rst

* remove plugins, libs used
* remove thanks section, see AUTHORS
* remove "nikola" from incremental compilation trivia fact (it does
  also incremental compilation)
  • Loading branch information...
commit 64da6b6f7308c603c6244a36100dc3c5e1b83a1b 1 parent cc69c66
@posativ authored
Showing with 101 additions and 151 deletions.
  1. +101 −48 docs/about.rst
  2. +0 −102 docs/idea.rst
  3. +0 −1  docs/index.rst
View
149 docs/about.rst
@@ -1,54 +1,107 @@
About Acrylamid
===============
-Supported Modules
-*****************
-
-- `jinja2 <http://jinja.pocoo.org/>`_ and `mako <http://www.makotemplates.org/>`_
- for pythonic templates.
-- `unidecode <http://pypi.python.org/pypi/Unidecode/>`_ for a better NFKD algorithm
-- `smartypants <http://http://daringfireball.net/projects/smartypants/>`_ &
- `typogrify <https://code.google.com/p/typogrify/>`_ – modern typography
-
-Markup languages
-****************
-
-- `reStructuredText <http://docutils.sourceforge.net/rst.html>`_ and `textile
- <https://github.com/sebix/python-textile>`_
-- `Markdown <http://daringfireball.net/projects/markdown/>`_ (or `Discount
- <https://github.com/trapeze/python-discount#id4>`_, a C implementation of Markdown)
-- any `Pandoc <http://johnmacfarlane.net/pandoc/>`_ dialect
-
-Extensions
-**********
-
-- syntax highlighting via `pygments <http://pygments.org/>`_
-- `AsciiMathML <http://www1.chapman.edu/~jipsen/mathml/asciimath.html>`_ via
- `python-asciimathml <https://github.com/favalex/python-asciimathml>`_
-- reStructuredText `Code directive <http://alexgorbatchev.com/SyntaxHighlighter/>`_,
- Sourcecode and YouTube directives inspired by blohg_
-- acronym definitions and implementation from the `Pyblosxom plugin`_
-- Hyphenation is based on `Frank Liang's algorithm
- <http://nedbatchelder.com/code/modules/hyphenate.py>`_ `TEX hyphenation patterns
- <http://tug.org/tex-hyphen/>`_
-
-.. _blohg: https://hg.rafaelmartins.eng.br/blohg/file/a09f8f0c6cad/blohg/rst/directives.py
-.. _Pyblosxom plugin: http://pyblosxom.bluesock.org/1.5/plugins/acronyms.html
-
-Thanks to
-*********
-
-- sebix_ <szebi@gmx.at> who forced me to make docs and work with linux' locale
- and also supplied the *textile* and *metalogo* filter.
-- moschlar_ who implemented Mako templating
-- 0x1cedd1ce_ for his code to ping to Twitter
-
-.. _sebix: http://sebix.github.com/
-.. _moschlar: http://www.moritz-schlarb.de/
-.. _0x1cedd1ce: http://0x1cedd1ce.freeunix.net/
-
-Ideas
-*****
+Acrylamid is not a dumb blog compiler. Over one thousand lines of code have
+been written to detect changes in your blog and reflect these changes with
+minimum effort in the output while on the other side being highly modular. How
+is this done?
+
+Fundamental Concepts
+--------------------
+
+#. Caching. Acrylamid caches *everything*. So if you have several pages on your
+ blog index and you add a new entry, it pulls all existing entries from its
+ cache without any recompilation.
+
+#. Explicit modification recognition. Only two things can change: content or
+ layout. If the content changes, only this specific item must be re-compiled.
+ If you modify your layout, all content is retrieved from cache.
+
+#. Lazy evaluation. Acrylamid is that lazy; it even delays the import of
+ libraries. If you write your current article in Markdown, why should it
+ initialize ``docutils`` that takes nearly half a second to import?
+
+That is the idea behind. Now how it is actually implemented. Instead of rushing
+from beginning to the end, we do it reverse.
+
+
+Implementation
+--------------
+
+View :
+ An Atom feed, an index page with a summarized listing of recent posts, a full
+ version of that entry, an articles overview. A view generates that and also
+ checks whether a page must be re-compiled or can be skipped.
+
+ Now the best: you can add as many views as you like. You route them to your
+ index page or render out a full-text feed beside a summarized feed. Acrylamid
+ will find out the most efficient way to compile your content to HTML.
+
+Filters :
+ A filter is like a UNIX pipe. It gets text, processes it and returns
+ text (preferably HTML). You can apply as many filters as you like all
+ content, per view or per entry. That's also the hierarchy. A filter
+ specified in an entry will always override per view or global filters (but
+ only if the filter is in conflict with other filters such as Markdown vs.
+ reStructuredText).
+
+You may ask why you need multiple filters per entry and/or per view? Well, let
+me explain: you write some text, and you are to lazy to sum up the context. A
+filter can do that for you. You prefer hyphenation in your browser, but don't
+want it in your feed. But you have to.
+
+Here is an example configuration::
+
+ FILTERS = ["Markdown", "hyphenation"]
+ VIEWS = {
+ # h1 means headings decreased by 1, h2 by 2 ...
+ '/:year/:slug/': {'view': 'entry', filters: ['h1', ]},
+ '/': {'view': 'index', filters: ['h1', 'summarize']},
+ '/atom/': {'view': 'atom', filters: ['h3', 'nohyphenate']}
+ }
+
+So, how does Acrylamid figure out, that the markup can be used for multiple
+routes? It basically builds a tree with all used paths and looks whether a
+path can be used more than once:
+
+
+.. blockdiag::
+
+ blockdiag concept {
+ orientation = portrait;
+ Markdown -> "h3" -> "/atom/" [default_fontsize = 20];
+ Markdown -> hyphenation -> "h1" -> "/:year/:slug/";
+ Markdown -> hyphenation -> "h1" -> summarize -> "/";
+ }
+
+You can clearly see that markdown conversion is only computed once and is re-
+used. That makes it possible to re-adjust the maximum of words you want to
+summarize without any markdown conversion. It simply uses the cached version.
+
+Using a disk cache makes it also possible to track changes. Each time you
+modify the filter chain (evaluated per entry) it figures out what
+intermediates are not used anymore and which ones are not affected.
+
+
+Trivia
+------
+
+Q : What is the overhead of saving each intermediate to disk?
+
+ I can only give my personal blog as comparison: 165 articles are using
+ 1.45 mb cache. Actually all intermediates are minimized with ``zlib``.
+
+Q : How fast is Acrylamid in comparison to Pelican, Octopress etc.?
+
+ For what it's worth: Pelican and Acrylamid are almost equally fast
+ in their default configuration, although Acrylamid has hyphenation active
+ and renders much more pages like tags and index.
+
+ When it comes to incremental updates, Acrylamid is much faster than
+ Pelican (something like "less than a second versus several seconds").
+
+Origin
+------
Acrylamid is a mixture of mainly three projects: PyBlosxom_, nanoc_ and
several complete rewrites (including data loss near the end) of Acrylamid_
View
102 docs/idea.rst
@@ -1,102 +0,0 @@
-Idea
-====
-
-Acrylamid is not a dumb blog compiler. Over one thousand lines of code have
-been written to detect changes in your blog and reflect these changes with
-minimum effort in the output while on the other side being highly modular. How
-is this done?
-
-
-Fundamental Concepts
---------------------
-
-#. Caching. Acrylamid caches *everything*. So if you have several pages on your
- blog index and you add a new entry, it pulls all existing entries from its
- cache without any recompilation.
-
-#. Explicit modification recognition. Only two things can change: content or
- layout. If the content changes, only this specific item must be re-compiled.
- If you modify your layout, all content is retrieved from cache.
-
-#. Lazy evaluation. Acrylamid is that lazy; it even delays the import of
- libraries. If you write your current article in Markdown, why should it
- initialize ``docutils`` that takes nearly half a second to import?
-
-That is the idea behind. Now how it is actually implemented. Instead of rushing
-from beginning to the end, we do it reverse.
-
-
-Implementation
---------------
-
-View :
- An Atom feed, an index page with a summarized listing of recent posts, a full
- version of that entry, an articles overview. A view generates that and also
- checks whether a page must be re-compiled or can be skipped.
-
- Now the best: you can add as many views as you like. You route them to your
- index page or render out a full-text feed beside a summarized feed. Acrylamid
- will find out the most efficient way to compile your content to HTML.
-
-Filters :
- A filter is like a UNIX pipe. It gets text, processes it and returns
- text (preferably HTML). You can apply as many filters as you like all
- content, per view or per entry. That's also the hierarchy. A filter
- specified in an entry will always override per view or global filters (but
- only if the filter is in conflict with other filters such as Markdown vs.
- reStructuredText).
-
-You may ask why you need multiple filters per entry and/or per view? Well, let
-me explain: you write some text, and you are to lazy to sum up the context. A
-filter can do that for you. You prefer hyphenation in your browser, but don't
-want it in your feed. But you have to.
-
-Here is an example configuration::
-
- FILTERS = ["Markdown", "hyphenation"]
- VIEWS = {
- # h1 means headings decreased by 1, h2 by 2 ...
- '/:year/:slug/': {'view': 'entry', filters: ['h1', ]},
- '/': {'view': 'index', filters: ['h1', 'summarize']},
- '/atom/': {'view': 'atom', filters: ['h3', 'nohyphenate']}
- }
-
-So, how does Acrylamid figure out, that the markup can be used for multiple
-routes? It basically builds a tree with all used paths and looks whether a
-path can be used more than once:
-
-
-.. blockdiag::
-
- blockdiag concept {
- orientation = portrait;
- Markdown -> "h3" -> "/atom/" [default_fontsize = 20];
- Markdown -> hyphenation -> "h1" -> "/:year/:slug/";
- Markdown -> hyphenation -> "h1" -> summarize -> "/";
- }
-
-You can clearly see that markdown conversion is only computed once and is re-
-used. That makes it possible to re-adjust the maximum of words you want to
-summarize without any markdown conversion. It simply uses the cached version.
-
-Using a disk cache makes it also possible to track changes. Each time you
-modify the filter chain (evaluated per entry) it figures out what
-intermediates are not used anymore and which ones are not affected.
-
-
-Trivia
-------
-
-Q : What is the overhead of saving each intermediate to disk?
-
- I can only give my personal blog as comparison: 165 articles are using
- 1.45 mb cache. Actually all intermediates are minimized with ``zlib``.
-
-Q : How fast is Acrylamid in comparison to Pelican, Octopress, Nikola?
-
- For what it's worth: Pelican and Acrylamid are almost equally fast
- in their default configuration, although Acrylamid has hyphenation active
- and renders much more pages like tags and index.
-
- When it comes to incremental updates, Acrylamid is much faster than
- Pelican (something like "less than a second versus several seconds").
View
1  docs/index.rst
@@ -20,7 +20,6 @@ https://github.com/posativ/acrylamid/.
advanced
conf.py
commands
- idea
filters/index
views/index
assets
Please sign in to comment.
Something went wrong with that request. Please try again.