DokuWiki

It's better when it's simple

User Tools

Site Tools


plugin:projects:documentation

Projects Plugin | Development

Projects Wiki Documentation

The Projects Wiki is a DokuWiki plugin that provides the ability to create, manage, and organize wiki pages that represent files.

SECURITY WARNING: There is a huge security risk when running on an publicly editable wiki, just as enabling the PHP embedding in wiki pages, i.e., it is equivalent of opening up access to the user and group that the Apache process is running with.

Download

Installation

  • 8-O Before you proceed: Read the security warning carefully, 5 times, and say to yourself: I do not want to use it in an publicly editable wiki.
  • Repeat the above step. 8-)
  1. As a dokuwiki plugin, you will of course need DokuWiki installed and working.
  2. Install this plugin as any dokuwiki plugin.
    • See plugin for instructions on how to install the plugin automatically using the download link above, which should always points to the latest version.
    • Alternatively, see plugins for the instruction on how to manually install a DokuWiki plugin.
  3. Create a namespace “:projects”
  • Anything in the “projects” namespace and its sub-namespace will be managed by this plugin, and thus become a Projects Wiki.
  • Read the security warning again, and again, and say to yourself: I do not and will not open up the editing access to the projects namespace to anyone that I do not trust 8-O

Overview

The files are organized into projects, corresponding to a namespace under the “:projects” namespace in the wiki. Thus a project is effectively a folder.

File types

The files can be:

  • a source file, which can be used to generate other files. For example, a latex file, a bibtex file, a matlab script, a C source code, etc.
  • a generated file, which can be a PDF file generated from a latex file, a figure generated by a matlab or an R script, a simulation program generated from a some C/C++ source codes.
  • a cross-link, which links to some file in another projects.

Representing a file

A wiki page is regarded to represent a file in a project if it contains the one of the project-file tags

<project-file type="source"/>
<project-file type="generated"/>

representing either a source file or a generated file. The tag used for a crosslink is similar, which will be discussed separately below. Note the tag ends with />, conforming to the XML standard.

The name of the file is the same as the page name. For example, if you want to create a latex file “mypaper.tex”, you create a wiki page with the same name “mypaper.tex”, and put the tag

<project-file type="source"/>

in it.

Dependency

Some files may depend on other files. For example, in order to generate a PDF file “mypaper.pdf”, we may need a latex file “mypaper.tex”. In this case, we say “mypaper.pdf” depends on “mypaper.tex”, or alternatively, “mypaper.pdf” uses “mypaper.tex”.

This dependency information is specified by a use tag. Specifically, if file A uses file B, we put the following use tag anywhere below the project-file tag in A.

<use name="B"/>

Again, note the tag terminates with />.

This is generally useful for generated files, because they usually need to be generated from other files, and thu uses these files. Source files can depend on other files as well. For example, a latex file may depend on a figure, which may in turn be generated from other sources.

Proper specification of the dependency guarantees that, when a used file is modified, all generated files depending on it directly or indirectly will be regenerated.

The contents of a source file

The contents of a source file is everything between a content tag below the project-file tag of a source file. For example, a page “note.txt” may contain

<project-file type="source"/>
<content>
See the file contacts.txt for all the contact information.
</content>
<use name="contact.txt"/>

The content of “note.txt” is then “See the file contacts.txt for all the contact information.”

Note that the tag is closed with </content>, and the text in between, including the end of lines, are copied verbatim to the content of the source file.

This example also shows that “note.txt” uses “contact.txt”, so any file generated from “note.txt” will be regenerated when “contact.txt” is changed.

A source file may contain multiple content tags. The actual content of the source file is the concatenation of all the contents in each tag. You can even specify a name for each tag for reference. For example,

The following latex code is the introduction section.

<content name="introduction">
\section{Introduction}
blah blah blah
</content>

Now it is the method section.

<content name="method">
\section{Method}
Whatever method description
</content>

defines two content tags. The real content is

\section{Introduction}
blah blah blah
\section{Method}
Whatever method description

This example also illustrates that you can put whatever text between tags. These text are treated as normal wiki text, and won't be included in the source file. This is useful to annotate the source file contents.

Recipes for generated files

Generated files are generated with some recipes. These recipes are commands issued on the server to generate the specified file. Usually, they are unix shell commands. Just like the contents of a source file, the recipes of a generated file are contents between recipe tags. For example, the content of a “mypaper.pdf” may be

<project-file type="generated"/>
<use name="mypaper.tex"/>
<recipe>
latex mypaper
bibtex mypaper
latex mypaper
</recipe>

The server will run the following commands

latex mypaper
bibtex mypaper
latex mypaper

to generate “mypaper.pdf”.

Similarly, there can be multiple recipe tags.

Syntax highlightinh

  • This feature is introduced in the 2011-05-17 version.

Both the recipe of a generated file and the content of a source file are syntax-highlighted. If not specified, the syntax is automatically guessed from the filename.

The syntax can also by specified manually at the file level, or at each content or recipe block level. Both ways are specified by the “highlight” property in the tag. The block level specification will override the file level one. Thus, it is possible to syntax highlight different blocks of a file differently. This may be useful if the file contains multiple segments in different languages, such as sweave files. The value of a property is a language name supported by GeSHi

For example, a source file may look like this:

<project-file type="source" highlight="bash"/>
This defines a bash script that passes a here document to to R.
<content name="bash">
R --vanilla --quient <<HERE

</content>
Here is the R script
<content name="R" highlight="rsplus">
x=c(0,1,2,3)
max(x)
</content>
Here is the closing of the here document.
<content name="close">

HERE
</content>

Note the newlines after the starting “HERE” and before the closing “HERE”. This is needed because when the 3 content blocks are concatenated together, the spaces and the first newline right after the tag are stripped. Without these newlines, the content of the file would be crammed together, like

R --vanilla --quient <<HEREx=c(0,1,2,3)
max(x)HERE

instead of the correct version:

R --vanilla --quient <<HERE
x=c(0,1,2,3)
max(x)
HERE

A cross-link file links to some file in another project. In the “note.txt” example above, the dependency “contact.txt” may be generated in another project “projects:contacts” by scanning all the senders of your incoming emails. In this case, you can put a cross-link file in your current project that points to “contact.txt” in the project projects:contacts. You will create a page named :contact.txt“ in your current project with

<project-file type="crosslink" linkto="projects:contacts:contact.txt"/>

So, the type="crosslink" specifies that this page represent a cross-link file, which links to the file represented by the page in linkto. Again, note that the tag ends with />.

Auto dependency of latex files

Latex source file are scanned automatically for \input{}, \include{}, \bibliography{}, and \includegraphics{} tags, and these files are automatically added as dependency.

Use uploaded files

Files uploaded to the namespace of the current project can be represented in the project by a generated file with the same file name, and empty or no recipe tag. For example, a page named “figure.eps” with either

<project-file type="generated"/>

as the only tag (and no recipe and dependency specified), or

<project-file type="generated"/>
<recipe>
</recipe>

represents an uploaded file “figure.eps”.

Errors when generating

If a generated-type file cannot be generated, an error will be displayed in the wiki page, with a log.

Editing

You can use the “Edit” button after the “content” or “recipe” label on the page of a source of target file.

Manually making or remaking a target file

Sometimes we may want to avoid automatic generation of a generated file, for example, if the generation of file is slow and you want to generate only when necessary. If this happens, or for any other reasons you need to regenerate (update) a file, just click on the “Remake” button in the file header on the wiki page.

Deleting a file

To delete a file, you can use the “Delete” button in the file header on the wiki page.

Managing projects

You can go to a management page with the “manage_files” action. This can be accessed with the “Manage files” button in the file header on the wiki page. Alternatively, you can use a link such as

[[?do=manage_files|Manage files]]

In the management page, you can delete and create a file, remake a generated file, or create a subproject.

plugin/projects/documentation.txt · Last modified: 2017-10-02 01:14 by Aleksandr