pcb-rnd knowledge pool


Specification of the pool node format

pool by Tibor 'Igor2' Palinkas on 2017-12-24

Tags: spec, contrib

node source



Abstract: n/a

  Each node is a directory in the svn repository, under trunk/web/pool/ . Directory names should be short, lower case words containing only alphanumeric characters and underscore (and no space).

Each directory has its main file, Body.html; it is a hand written html file without header. It uses only the most commong tags: <p>, <pre>, <i>, <b>, <code>, <br>, <table>, <tr>, <th>, <td>, <ul>, <ol>, <li>, <img> with alt and src, <a> with href. Headers should be numbered from <H1> (the CGI will renumber them to fit in the final page).

Local resources, e.g. images, are placed in the same directory and referenced in the img src or the a href without path. A sibling node is linked in a href as "../nodename". Resource files should have short, alphanumeric names and should start with a lowercase letter. Embedding video should be done using the html5 <video> tag, using this template .

Beside the actual content, there are metadata. Each metadata goes in a separate plain text file:

filename function
Abstract A single paragraph short summary of the content (no html tags)
Author List of authors, each name in a new line
Tags A comma separated list of tags
Title The title of the node, a few words long
Cdate Content creation date of the node in yyyy-mm-dd format

Tags are free form. There are many conventions for tags, which new nodes should try to follow. The most important tag is the "class" tag, which, by the convention, should be the first tag:

tag meaning
howto howto or tutorial, explains the process of doing a specific task, typically to users
announcement announce a feature
index index node, a structured overview of a wider topic; links a few other nodes
insight an article describing how something works under the hood, not cocentrating on how users could perform daily tasks; might be interesting for both users and developers
dev notes for developers (and hardcore users)
spec specification (of a file format, of a set of conventions, etc.)
roadmap detailed plans on how something is going to be achieved (often the result of a poll)
RFC proposal, Request For Comment material (this tag usually changes into one of the other primary tags when the document is finalized)
admin administrative questions related to running the project

Other tags that are pretty common:

tag meaning
format file format related node
schematics schematics (and netlist) related node
focus is on getting data into pcb-rnd
focus is on getting data out of pcb-rnd
contrib material useful for people looking for contributing
menufile the node contains menu file related info that needs updating on menu file change (screenshots of menus, hotkey info)

How to create a new node: just create a new directory, create Body.html and the metadata files, set the proper tags and commit. It will be automatically published and searchable online within a few seconds after the commit.