Wiki Doc
This is a project for creating documentation for the Emacs-Wiki and Planner libraries for Emacs.
Visit PlannerEtAl for a starting point to the whole picture to planning.
Visit EmacsWiki for documentation of this Emacs mode.
Nothing in these pages is finished yet. I descovered Planner Mode since recently, when I was desperately looking for a tool to share my planning with an assistent. As my workload grew, I needed to hire someone to help me out with administrative and organisational tasks. The publishing feature allows me to convey information easily and the Wiki way for keeping related things proved mostly useful for me.
However the tools have only little directly accesible documentation -- if we speek of persons who do not fluently read Elisp sources in English -- and the current Wiki and Planner are perceived primarily for personal planning. So, instead of actually planning I am currently into finding out how to changes this situation.
EmacsWiki
The File is created primarily from the Elisp sources' documentation. It is of course written as an Emacs-Wiki page.
The goal is, to provide texinfo files from the Wiki Pages, which can be included in the info documentation.
Wishlist
Current Directory
Emacs-Wiki maintains a list of directories, which all belong to one Wiki-Project. When you create a new page by inserting a WikiName and following the link, the corresponding file is created in the same directory as the original page.
This may be beneficial for some projects, for others it may not. One example is, when to people (Peter and Paul) create independently content for a Wiki in different (shared) directories, it may be desirable that all new pages created by Paul reside in "his" directory, while he still is able to edit Peter's pages, e.g. to put a link to one of his (new) pages into them.
To achieve this, EmacsWiki needs to know which is the "current" or default directory to put pages into. Of course it must be possible to switch between the two aproaches.
The following patch makes the first directory in `emacs-wiki-directories' the current directory for writing new wiki pages into it. If you want to change the current directory, you have to reorder the list.
Add a new customizable variable:
(defcustom emacs-wiki-use-current-directory nil "If true, use the first directory in emacs-wiki-directories for new pages. Otherwise (the default) if there are several directories in the wiki, create a new page in the same directory where a new link is first followed." :type 'boolean :group 'emacs-wiki)
Change the function `emacs-wiki-visit-link':
(defun emacs-wiki-visit-link (link-name &optional refresh-buffer other-window)
"Visit the URL or link named by LINK-NAME.
... 'find-file)))
(setq newbuf
(if (null file)
(funcall find-file-function
(expand-file-name
base
;; LEG15062004
(if emacs-wiki-use-current-directory
(car emacs-wiki-directories)
(file-name-directory (buffer-file-name)))))
(funcall find-file-function file)))
(when tag
...
To reorder the `emacs-wiki-directories' it would be very desireable, if someone (with better Elisp knowledge and skills than I) would write an interactive function with completion, to select one of the directories in `emacs-wiki-directories' to put on top of the list.
By now a feasable aproach ist to create as many EmacsWiki projects as there are directories, and set `emacs-wiki-directories' in each of them with the specific directory on top of the list. If you use the scenario of colaborative editing, this means, that on each computer/account there is one of these incarnations of the project.
The standard behaviour of EmacsWiki with several wiki directories is
somewhat moot anyway, because you cannot start an empty project with
several directories and forcibly create new pages in any other than
the first directoy in the `emacs-wiki-directoy' list. Ok: you can
probaply do it by entering the new link and C-x C-w the new page,
will have to try it out...
The real motivation for the "current-directory" is, because I want it to use in planner mode, with each sub-project in it's own directory. If I work on one subproject, new pages are created in that directoy, and . However at this time this is not possible, because Planner Mode does not support multiple Wiki directories. Why?!
List of public directories
In the same mood as the last paragraph in the previos section I wanted to be able to "screen-out" some directories when publishing.
Suppose I'am working for client Tritech and Forecom and have of course my own personal schedule. Together with my assistant this would make four Planner directories:
("~/peter/Plans" "~/paul/Plans" "~/tritech/Plans" "~/forecom/Plans")
</exampl>
where documentation, notes, appointments etc. are held. When
publishing the Tritech documents I wouldn't want to publish neither
Forecom's Plans nor Paul's. By setting the variable
`emacs-wiki-public-directories' to =("~/peter/Plans"
"~/tritech/Plans")= only files within these two directories would be
published. The following patches achieve this goal.
Add the variable `emacs-wiki-public-directories':
<example>
(defvar emacs-wiki-public-directories nil
"*A list of directories selected for publishing.
This variable only applies if `emacs-wiki-use-mode-flags' is nil.
If this is not nil, emacs-wiki-private-pages does not apply")
By setting this variable to nil by default, no restriction occurs and
all directories are taken into account.
Substitute the function `emacs-wiki-private-page-p' with:
(defun emacs-wiki-private-p (name)
"Return non-nil if NAME is a private page, and shouldn't be published."
(if name
(cond
(emacs-wiki-use-mode-flags
(let* ((page-file (emacs-wiki-page-file name t))
(filename (and page-file (file-truename page-file))))
(if filename
(or (eq ?- (aref (nth 8 (file-attributes
(file-name-directory filename))) 7))
(eq ?- (aref (nth 8 (file-attributes filename)) 7))))))
((let ((private-pages emacs-wiki-private-pages) private)
(while private-pages
(if (string-match (car private-pages) name)
(setq private t private-pages nil)
(setq private-pages (cdr private-pages))))
private))
(emacs-wiki-public-directories
(let ((dirlist emacs-wiki-public-directories)
(private t))
(while dirlist
(setq d (car dirlist) dirlist (cdr dirlist))
(if (file-exists-p (concat d "/" name))
(setq dirlist nil private nil)))
private)))))
This function substitutes a if by a cond construct, leaving the former tests for page-"privacy" in their place and finally checking if `emacs-wiki-public-directories' is set. In this case additional restrictions apply - i.e. if it were a public page but is not in a public directories, the page is considered private.
This approach allows a very fine grained control, since you can disable publishing on a per page and on a per directory bases.
In actuality I suppose almost nobody uses the multi-directory feature of Emacs-Wiki, so the public-directory approach is pointless. However if you need to create a web site with public and private pages you can set up a Wiki-project with two (or more) directories, where you separate -- using the "current directory" feature -- public and private pages in different Wiki directories. You set up the publishing directory and the publishing prefix respectively.
Then you define another Wiki-project, with the same directories, but now the directories allowed for publication are the private ones, and the publishing-directory and -prefix is another.
On your Webserver you protect the private pages with a password or whatever authentication method is aplicable.
I suppose that it needs some tweaking or magic to get the links from one page to the other work, mhmm... that would be the next wishlist item.
The aproach taken is somewhat inefficient, because we could just traverse the public directories when publishing, instead of checking all files in all directories if they are public or not. However I did not find out how to do this easily. There seem to be issues with `emacs-wiki-file-alist' and `emacs-wiki-complete-alist' returning both always all files of all projects.
No subdirectory traversal
I use "./html" as the publishing directory, so the published html-code always went "close" to the source, and I never have to think about where to put it or where to find it.
In the -dev version of emacs-wiki all subdirectories of the wiki directories are descended to find emacs-wiki pages when publishing. This has the effect, that yet published pages (.html) get sub-published as .html.html ad infitum...
Is there a way to switch this off?
Customize cleanup
Several customizable variables are meant to be changed in every Wiki project, one example is `emacs-wiki-directories'. They should rather be declared as user setable variables than as customizable variables.
Subdirectory tagging
The multi-directory feature of EmacsWiki seems hardly used and not thouroughly supported either. Recent versions of EmacsWiki not only scan each directory for Wiki pages, but also subdirectories of them too - I suppose to support hierarchies of Web-directories. The function emacs-wiki-file-alist is magical to the Wiki in the sense that it returns a list of al page names belonging to the Wiki, each cons'ed with the complete filename. This comes close to a page/properties list.
One difficulty with publishing multiple directory Wiki's is, when they contain pages with the same name in different directories. In this case only one of the files is published. Also, when following a link, always the first page of all pages with the same name is beeing shown.
`emacs-wiki-directories' could evolve into a data structure, where each of the directories is a) tagged with a name b) individual properties for each directory are stored. The publishing directory comes to my mind as a candidate, as well as individual private-page regular expressions etc.
The tag could be used to differentiate two pages with the same name in different directories. It can be brought into game dinamically. While no second/third page with the same name exists, no tag needs to be used. In the moment a page with a yet existing name but a different directory is found one of them is automatically tagged, in dependece of priority. The order of directories in `emacs-wiki-directories' can determine which of them is tagged, the firstcoming directory does not need tagging, the second is tagged. Tagging would occur at this moment by searching for all Wiki links to the page and changing them. The tag would naturally be a prefix to the Wiki name, similar to the InterWiki feature. This would also allow to use it directly as a subdirectory name in publishing.
Example:
emacs-wiki-directories:
((WikiDoc . ((directory . "~/WikiDoc")))
(jorge . ((directory . "~/jorge/WikiDoc")
(private-pages . "Makefile\|index.wn")
(use-mode-flags . nil)))
(peter . ((directory . "~/peter/WikiDoc")))
(paul . ((directory . "~/paul/WikiDoc"))))
Each of the directories could have it's own WelcomePage. They would be addressed by "WelcomePage" in the case of the "~/WikiDoc" directory, in the other cases by, "jorge/WelcomePage", "peter/WelcomePage" and "paul/WelcomePage" respectively.
The project settings could follow a similar scheme, I am inventing a new variable here:
emacs-wiki-project-settings ((name . "Wiki Documentation Project") (description . "This project is a colaborative effort between jorge, peter, paul and the net comunity to create first quality documentation for the EmacsWiki mode") (publishing-directory . "~/WikiDoc/html"))
When publishing to html, the pages would be published into
~/WikiDoc/html in the case of the "WikiDoc" directory, and into
~/WikiDoc/html/jorge, ~/WikiDoc/html/peter and
~/WikiDoc/html/paul respectively for the others, as would be
arranged for the relative links to point into these directories.
Bugs
- Once an emphasis markup terminates at the end of the line and you have left it, you cannot add new characters at the end of the line.
- In-page references cannot use #CamelCase.
- the > verse markup respects quoteing and centering. The <verse> environment does not.
- Simple tables seem not to follow paragraph formatting.
- Simple tables split themselves if you use = markup.
- you cannot type `=' in monospace.
- allout minor mode screws up the highlighting and potentially destroys the headings...
Status
- The EmacsWiki manual is in a somewhat useable state now. At least all the initial material mark up correctly in HTML.
- I have not found the time to convert it into texinfo, info and pdf format, and less to publish and link these on the Website.
References
By now, some references go here, they will be incorporated into the documents.
- http://sacha.free.net.ph/notebook/wiki/
- The homepage of the Maintainer of Emacs Wiki and Planner
- http://emacswiki.org/cgi-bin/wiki.pl?EmacsWikiMode
- Page about Emacs Wiki on the - well - Emacs Wiki Website.
- http://newartisans.com/johnw/programs.html
- Original Author's Page with his Software.
:: David O'Toole, uses planner to maintain schedules for other people as well - could not conect to his advogato page
- http://tkd.kicks-ass.net/
- Gary Vaughn uses hierarchical directories for his Wikis
or
- http://www.magma.com.ni/~jorge
- Got to my Homepage