pdocbot

A tool for maintaining POSHDOC collections

About

pdocbot is a commandline application which is started in the top directory of a POSHDOC collection and can be feed with commands on stdin, which allow to explore and maintain the collection.

A first Tcl implementation of pdocbot is available from the MagmaSoft Darcs repository

Usage

pdocbot can make use of templates and configuration files in the pdocbot subdirectory of the POSHDOC collection, if present.

Features

Implemented

Create (missing) Topics

Recurse over the collection and for each POSHDOC:
Find all local links
If the target is not found
Create the target from the Topic template
Setting title, description and subtitle from the local link metadata

Also be able to create a Topic on demand, specifying a path, the title and optionally a template, the description, subtitle and author.

Create backlink pages

When required in a page create a backlink listing page and link it over the page title.

<h1><a href="{{ROOT}}/backlinks/PAGE.html">TITLE<a/>

Allow to do it over the whole collection.

Note: only backlink creation over whole collection is implemented. it' is still buggy and "old" pages have to be changed to link to their backlinks.

Wanted

Update `created` and `updated` timestamps

Recurse over the collection and for each POSHDOC:
Read creation and modification time of the POSHDOC file
update body/footer/small/time[@class='dt-published'] and body/fo…='dt-updated' accordingly. See metadata

Alternatively take the timestamps from the underlying version control system – especially from Darcs.

Insert/update author information

(Re-)write author information in body/footer/small/a[@rel='p-author'] in specified POSHDOCs

Create links to terms

Convert

<mark class="todo" title="ToDo: Link to term">TERM</mark>

with an optional rel="PATH" to

<a href="PATH" title="DESCRIPTION|SUBTITLE|TITLE">TITLE</a>

Update the ToDo page

Find

<mark class="todo" title="ToDo: ACTION">ToDo: … </mark>

Add a local link with a unique id="todoN" to it on the ToDo page and replace it with

<mark class="todo"><a href="ROOT/ToDo.html#todoN" title="ToDo: ACTION">ToDo</a>: … </mark>

Ideas

Add/update/remove presentation and navigation

Add/update style sheets and javascript files.
Deposhify POSHDOCs or HTML files.
Add/update the <nav> section with:
- Home, Up, Prev, Next
- Trails
- Language
navigation.

`fmt` — HTML re-formatter

Pretty-(re)format the POSHDOC HTML files similar to Emacs html-mode.

Notes:

@title and meta@description attributes should never be wrapped.

Nested headings should probably be intended too.

Make the wrapping column somewhat greater then Emacs.

Transclusion of Topics into master documents

Allow to create master documents with a content structure with transclusion links to Topics.