etc/emacs-wiki-migration.txt

   1
   2 This document describes the process of migrating from emacs-wiki to Muse.
   3
   4 Features
   5 ========
   6
   7 Muse only
   8 ---------
   9
  10 Features that exist in Muse, but not emacs-wiki:
  11
  12  - Nested lists.
  13
  14  - Publishing to multiple other formats, such as LaTeX and Docbook.
  15
  16  - Escaping special characters automatically throughout the entire
  17    document, so that you don't have to.
  18
  19  - Ability to use a different header and footer in different projects,
  20    by creating your own publishing style.
  21
  22  - Ability to surround some Muse markup with the <verbatim> tag, which
  23    causes is to not be treated as markup.  This is useful for
  24    publishing the "|" character as-is, without turning the current
  25    line into a table.
  26
  27  - Improved detection of paragraphs, which results in HTML that meets
  28    various W3C standards.
  29
  30  - Journalling mode that is capable of publishing to RSS 2.0 or RSS
  31    1.0 (RDF).
  32
  33  - Embedding LaTeX code into a document by turning it into an image.
  34    This is in muse-latex2png.el.
  35
  36 emacs-wiki only
  37 ---------------
  38
  39 The reason that most of these have not been implemented is lack of
  40 demand.  If you want to see these features implemented, please send an
  41 email to the muse-el-discuss mailing list, describing a good use case
  42 for them.
  43
  44  - Publishing bookmarks in XBEL format.  The bk2site program --
  45    available separately -- does an adequate job, so this was not
  46    implemented for Muse.
  47
  48  - Macros, i.e. keywords like %this%, that expand to some text upon
  49    publishing.
  50
  51  - Global IDs.
  52
  53  - Menu generation.
  54
  55  - PGP encryption of regions with the <gpg> and <gpge> tags.
  56
  57  - The <redirect> tag.
  58
  59  - Publishing of ChangeLog files.
  60
  61  - The keybinding `C-c C-r': rename wiki link at point.
  62
  63  - The keybinding `C-c C-D': delete wiki link at point.
  64
  65  - The #style directive.
  66
  67  - Using the title of the page in a generated index page, rather than
  68    the filename of the page.
  69
  70 Specifying Projects
  71 ===================
  72
  73 Here is an example emacs-wiki-projects setting.
  74
  75 (setq emacs-wiki-projects
  76       '(("WebWiki" .
  77          ((emacs-wiki-directories . ("~/WebWiki"))
  78           (emacs-wiki-project-server-prefix . "/web/")
  79           (emacs-wiki-publishing-directory
  80            . "~/public_html/web")))
  81         ("ProjectsWiki" .
  82          ((emacs-wiki-directories . ("~/ProjectsWiki"))
  83           (emacs-wiki-project-server-prefix . "/projects/")
  84           (emacs-wiki-publishing-directory
  85            . "~/public_html/projects")))))
  86
  87 And here is the corresponding muse-project-alist setting.
  88
  89 (setq muse-project-alist
  90       '(("Website" ("~/WebWiki"
  91                     :default "WelcomePage")
  92          (:base "html"
  93                 :path "~/public_html/web"))
  94         ("Projects" ("~/ProjectsWiki"
  95                      :default "WelcomePage")
  96          (:base "html"
  97                 :path "~/public_html/projects"))))
  98
  99 Note that there is no need to specify a prefix.  Muse will
 100 automatically figure out what the relative paths in links to Muse
 101 files should be.
 102
 103 If you want to be able to link to another project entry that is on a
 104 different domain, then you must use :base-url in every project entry.
 105 An example of this follows.
 106
 107 (setq muse-project-alist
 108       '(("Website" ("~/WebWiki"
 109                     :default "WelcomePage")
 110          (:base "html"
 111                 :base-url "http://web.example.org/web"
 112                 :path "~/public_html_1/web"))
 113         ("Projects" ("~/ProjectsWiki"
 114                      :default "WelcomePage")
 115          (:base "html"
 116                 :base-url "http://projects.example.org/projects"
 117                 :path "~/public_html_2/projects"))))
 118
 119 Special Topics
 120 ==============
 121
 122 Including multiple directories
 123 ------------------------------
 124
 125 With emacs-wiki, this was done by setting the
 126 `emacs-wiki-recurse-directories' option to non-nil.
 127
 128 With Muse, this can be accomplished by including an entry in your
 129 muse-project-alist setting that causes entries for a directory and all
 130 subdirectories to be created.  This does not work when using the
 131 customize interface to set `muse-project-alist'.
 132
 133 Here is an example:
 134
 135     ("Blog" (,@(muse-project-alist-dirs "~/Blog")
 136              :default "index")
 137
 138      ;; Publish this directory and its subdirectories.  Arguments
 139      ;; are as follows.  The above `muse-project-alist-dirs' part
 140      ;; is also needed, using Argument 1.
 141      ;;
 142      ;;  1. Source directory
 143      ;;  2. Output directory
 144      ;;  3. Publishing style
 145      ;;  remainder: Other things to put in every generated style
 146      ,@(muse-project-alist-styles "~/Blog"
 147                                   "~/public_html/blog"
 148                                   "blosxom"))
 149
 150 Generating an Index page
 151 ------------------------
 152
 153 In emacs-wiki, the page specified by `emacs-wiki-index-page' is an
 154 automatically generated index page.
 155
 156 Muse does not automatically create this file.  If you want an
 157 automatic index file to be generated, then create a file and place the
 158 following contents (between the lines of underscores) in it.
 159
 160 _____
 161 #title Index
 162
 163 <lisp>(muse-index-as-string t t t)</lisp>
 164 _____
 165
 166 Then, add a :force-publish tag to the paths part of the project entry
 167 in muse-project-alist.  Example:
 168
 169     ("Website" ("~/Web/"
 170                 :force-publish ("WikiIndex")
 171                 :default "WelcomePage")
 172      (:base "xhtml"
 173             :base-url "http://mydomain.org/"
 174             :path "~/public_html"))
 175
 176 License
 177 =======
 178
 179 This file may be used, distributed, and modified without restriction.