doc: Fetch manual from the Wiki

- Already reorganised the manual page on the wiki for this purpose.

- Fix several issues with the Docbook export of MoinMoin.

  - Replace / in title with a space.

  - Remove revision history.

  - Convert image dimensions to points from pixels.

  - Fix incorrect wiki paths.

- Implement mechnism for downloading images and using them with
  relative paths.

- Remove the old way of compiling the manual.  Its contents are mostly
  not applicable for end users.  Design documents are outdated.  INSTALL
  and HACKING talk about Plinth installation not FreedomBox in general.
  A fresh man page will be written later.
This commit is contained in:
Sunil Mohan Adapa 2015-09-16 22:24:54 +05:30 committed by James Valleroy
parent 9d18759de5
commit ef2d3a4787
7 changed files with 232 additions and 263 deletions

View File

@ -14,7 +14,6 @@ otherwise.
- data/etc/apache2/plinth.conf :: -
- data/etc/apache2/plinth-ssl.conf :: -
- data/etc/sudoers.d/plinth :: -
- doc/Makefile :: -
- static/themes/default/FreedomBox-Identity-Manual.pdf :: -
- static/themes/default/FreedomBox-Logo.7z :: [[http://thread.gmane.org/gmane.linux.debian.freedombox.user/4124/focus=4439][GPL3+/CC-BY-SA]]
- static/themes/default/readme.md :: [[file:themes/default/readme.md::This%20theme%20is%20free%20software%20offered%20to%20you%20under%20the%20terms%20of%20the%20GNU%20Affero%20General%20Public%20License,%20Version%203%20or%20later:][GNU Affero General Public License Version 3]]

View File

@ -1,108 +1,65 @@
DOCDIR=../dist/doc
#!/usr/bin/make -f
#
# This file is part of Plinth.
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU Affero General Public License as
# published by the Free Software Foundation, either version 3 of the
# License, or (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU Affero General Public License for more details.
#
# You should have received a copy of the GNU Affero General Public License
# along with this program. If not, see <http://www.gnu.org/licenses/>.
#
PANDOC=pandoc
PDFLATEX=pdflatex
MANUAL_URL="https://wiki.debian.org/FreedomBox/Manual?action=show&mimetype=text%2Fdocbook"
OUTPUTS=freedombox-manual.pdf freedombox-manual.html freedombox-manual.part.html
# List text files in the order in which you want them to appear in the
# complete manual:
SOURCES=README.mdwn INSTALL.mdwn hacking.mdwn COPYING.mdwn
MAN_SOURCES=$(patsubst COPYING.mdwn,copyright_notice00,$(SOURCES))
all: $(OUTPUTS)
NEWLINE_SOURCES=$(patsubst %,% oneline.txt,$(SOURCES))
NEWLINE_MAN_SOURCES=$(patsubst %,% oneline.txt,$(MAN_SOURCES))
# Do not edit the manual page in this directory. The manual is
# maintained as separate pages on the FreedomBox wiki and aggregated
# into a single page using the MoinMoin include feature. Then it is
# exported as Docbook format and kept here.
#
# It is important to keep a copy of the manual in this source tree
# because Debian packages promise an entire source tree including the
# documentation.
#
# Use 'make fetch' to retrieve the latest manual from the wiki and
# commit it to the repository. The wiki page is already reviewed, so
# commits that update the manual just using the 'fetch' target do not
# require further reviews.
.PHONY: fetch
fetch:
wget --quiet -O - $(MANUAL_URL) | \
xmllint --format --output freedombox-manual.raw.xml -
xsltproc --output freedombox-manual.xml fixes.xslt freedombox-manual.raw.xml
xsltproc fetch-images.xslt freedombox-manual.raw.xml | sort -u | \
awk '{print "wget --quiet -O images/" $$1 " " $$2}' | sh
rm -f freedombox-manual.raw.xml
HTML=plinth.html $(patsubst %.mdwn,%.html,$(SOURCES))
HTML_PART=$(patsubst %.html,%.part.html,$(HTML))
LATEX=plinth.tex $(patsubst %.mdwn,%.tex,$(SOURCES))
PDF=plinth.pdf $(patsubst %.mdwn,%.pdf,$(SOURCES))
MAN=plinth.1
## If you want PDF or Latex files, do them separately. They're not made by default.
%.pdf: %.xml
xmlto --with-dblatex pdf $<
OUTPUTS=$(HTML) $(MAN) $(HTML_PART)
DIST_OUTPUT=$(patsubst %,$(DOCDIR)/%,$(OUTPUTS))
all: oneline.txt $(OUTPUTS) Makefile
$(DOCDIR)/%: %
cp $< $@
dist: $(DIST_OUTPUT)
###############################################################################
oneline.txt: Makefile
perl -e 'print "\n"' > oneline.txt
$(SOURCES):
@rm -f $@
if [ -f ../$(patsubst %.mdwn,%.md,$@) ]; then \
ln -s ../$(patsubst %.mdwn,%.md,$@) $@; \
else \
ln -s ../$(patsubst %.mdwn,%,$@) $@; \
fi
###############################################################################
##
## MAN PAGES
##
$(MAN): $(SOURCES)
@csplit -s -f copyright_notice COPYING.mdwn '/##/'
cat $(NEWLINE_MAN_SOURCES) | perl -pe 'BEGIN { $$/=undef } $$_ =~ s/\n\n#\s.*/\n/gm; $$_ =~ s/\n\n#/\n\n/gm; $$_ =~ s/(\n\n#\s.*)/uc($$1)/gme' > .make_man
$(PANDOC) -s -t man -o $@ .make_man
@rm -f copyright_notice0? .make_man
manpages: $(MAN)
###############################################################################
##
## LaTeX
##
%.tex: %.mdwn
$(PANDOC) -s --toc -f markdown --standalone -o $@ $<
hacking.tex: hacking.mdwn
$(PANDOC) -s --toc -f markdown -o $@ hacking.mdwn
plinth.tex: $(NEWLINE_SOURCES)
$(PANDOC) -s --toc -f markdown -o $@ $(NEWLINE_SOURCES)
latex: $(LATEX)
###############################################################################
##
## HTML
##
# This gets us the html sections complete with TOC, but without the
# HTML and head section boilerplate. /help/page uses the parts.
%.part.html: %.html
csplit -s -f $@ $< '%.*<body>%'
sed '1d' $@00 > $@01
csplit -s -f $@ $@01 '/<\/body>/'
mv $@00 $@
rm $@01
perl -pe 'BEGIN {undef $/} s/.*<body[^>]*>(.*)<\/body>.*/$1/s' $< > $@
%.html: %.mdwn Makefile
$(PANDOC) -s --toc -f markdown -o $@ $<
plinth.html: $(NEWLINE_SOURCES) Makefile
@csplit -s -f copyright_notice COPYING.mdwn '/##/'
$(PANDOC) -s --toc -o $@ -f markdown $(NEWLINE_MAN_SOURCES)
@rm -f copyright_notice0? .make_man
%.html: %.xml
xmlto html-nochunks $<
html: $(HTML) $(HTML_PART)
###############################################################################
%.pdf: %.tex
$(PDFLATEX) -interaction=batchmode $< >/dev/null
$(PDFLATEX) -interaction=batchmode $< >/dev/null # yes, do it twice so the toc works
.PHONY: clean
clean:
rm -f $(OUTPUTS)
pdf: $(PDF)
###############################################################################
clean-latex:
rm -f *.log *.out *.aux *.toc *.tex
clean: clean-latex
rm -f $(OUTPUTS) README.mdwn INSTALL.mdwn COPYING.mdwn \
copyright_notice0? \#*\# oneline.txt *.pdf

View File

@ -1,50 +0,0 @@
<!-- -*- mode: markdown; mode: refill; fill-column: 80 -*- -->
# Plinth's Design
Structurally, Plinth is very simple. It's nothing more than a modular system to
hook a web UI to the command line and the underlying system.
Users enable modules which turn on features on the box and run actions. The
only data Plinth itself should store are the modules users have and haven't
enabled. The rest of the information that Plinth interacts with is read from
and written to the appropriate system configuration files.
The most important files in the Plinth project are the modules (in the
`plinth/modules` directory). Those files create web pages that present
configuration options to the user and, when the user accepts the configuration,
runs the relevant action scripts.
In the simplest case, the user navigates to http://freedombox.lan/plinth/hello,
which runs the `plinth/modules/hello` file and displays the output as a web
page. When the user hits "Submit" on the hello page's form, the hello module
runs the `plinth/actions/hello` script, which takes the user's input, escapes
it, removes any suspect input or dangerous options (by applying a **whitelist**
to the user's input) and then passing the remaining, safe, options to the
`/bin/hello` program. The module chooses whether or not to display the output,
and the process is complete.
For example:
1. User requests http://freedombox.lan/plinth/hello
2. Plinth returns the response from `plinth/modules/hello`.
3. User submits Hello form.
4. Hello module runs `plinth/actions/hello`.
5. Hello action removes unsafe input.
6. Hello action runs hello system binary with only safe input.
7. Hello module may display output from hello binary.
8. The hello configuration process is complete.
In the above example, control flows in one of two ways:
1. `URL -> Module -> User`, where the user hasn't performed an action.
2. `URL -> Module -> Action -> Binary -> User`, where the user configures the
system.

View File

@ -1,118 +0,0 @@
# First Connection: Initial user configuration.
The Plinth first-connection process has several stages:
0. The user connects to Plinth for the first time and is redirected from
the home page to the Hello page.
1. The user sets the Box's name, the administrator's name and
password, and the box's PGP key (optional).
2. The box generates and the user receives any PGP keys.
3. The box detects the network's configuration and restarts networking.
4. The user interacts with the box normally.
## Stage 0: Connection
The user connects their client device, via Ethernet cable, directly to
the FreedomBox, and Plinth realizes that it hasn't been configured.
The user is automatically (non-interactively) redirected from the home
page to the Hello page.
## Stage 1: Hello
The user's first (interactive) interaction with Plinth is on the Hello
page, where they set these required items:
- Box's Name (hostname).
- Plinth Administrative User's Name.
- Plinth Administrative User's Password.
The user can also set these optional items:
- Box's *Private PGP Key.*
- User's *Public PGP Key.*
### TODOs
- [ ] Allow the user to provide the Box's *Private PGP Key.*
- [ ] Allow the user to provide their own *Public PGP Key.*
- [ ] Hide the key management tools under an advanced options menu.
- [ ] Add space for the administrative user's name and password in the
printed manual.
- [ ] Add space for the normal (non-administrative) user's name and
password in the printed manual.
## Stage 2: Identity Configuration
If the user didn't provide a PGP for the Box, box generates its own PGP
key. Also, if the user didn't provide their own public PGP key, the box
generates one for the user.
The user downloads all PGP keys provided by the box.
### TODOs
- [ ] Create PGP keys.
- [ ] Allow user to download PGP keys.
- [ ] Users need client-side tools to manage downloaded PGP keys.
## Stage 3: Networking Configuration
The printed manual instructs the user how to set up their local
network and uses diagrams to teach users to differentiate between a
router and modem. If the user only has a modem and their FreedomBox
doesn't have multiple ethernet ports, then I don't know what they'll
do. If we don't detect a router, the FreedomBox needs a minimum of
two network interfaces so the client device can connect to the
Internet.
----
The FreedomBox detects the current network configuration and adjusts
itself accordingly, configuring itself per the chart, below:
| Ethernet Ports | Modem | Modem + Router |
|----------------+-------+----------------|
| One | M1 | MR1 |
| Two | M2 | MR2 |
After network detection is complete, the FreedomBox asks the user to
correct the network configuration (plugging the right cables into the
right ports) and restarts networking.
The user's client device must still be able to connect to the Internet
after this configuration is complete. If not, the configuration is
invalid and should not be used. At a minimum, the user should be
warned that they're about to remove their client device from the
Internet.
### M1: Modem and 1 Ethernet Port
(RaspberryPi + Modem + Client Device)
(We may need to require a wireless modem on the RPi before this can be
a valid configuration.)
### M2: Modem, and 2 Ethernet Ports
(DreamPlug + Modem + Client Device)
### MR1: Modem Router, and 1 Ethernet Port
(RaspberryPi + Modem + Router + Client Device)
### MR2: Modem Router, and 1 Ethernet Port
(DreamPlug + Modem + Router + Client Device)
### TODOs
- [ ] Detect the current network configuration.
## Stage 4: Normal Interaction
Networking has restarted and the user can interact with the FreedomBox
normally.

67
doc/fetch-images.xslt Normal file
View File

@ -0,0 +1,67 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
#
# This file is part of Plinth.
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU Affero General Public License as
# published by the Free Software Foundation, either version 3 of the
# License, or (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU Affero General Public License for more details.
#
# You should have received a copy of the GNU Affero General Public License
# along with this program. If not, see <http://www.gnu.org/licenses/>.
#
-->
<xsl:stylesheet version="1.0"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
<!-- Set output method to text -->
<xsl:output method="text"/>
<!-- Process and ignore all nodes by default -->
<xsl:template match="@*|node()">
<xsl:apply-templates select="@*|node()"/>
</xsl:template>
<!-- Output URLs from imagedata nodes -->
<xsl:template match="imagedata">
<xsl:call-template name="filename">
<xsl:with-param name="path" select="@fileref"/>
</xsl:call-template>
<xsl:text> "</xsl:text>
<xsl:value-of select="@fileref"/>
<xsl:text>"&#010;</xsl:text>
</xsl:template>
<!-- Output just the filename from a URL -->
<xsl:template match="@fileref[parent::imagedata]">
<xsl:attribute name="fileref">
<xsl:call-template name="filename">
<xsl:with-param name="path" select="."/>
</xsl:call-template>
</xsl:attribute>
</xsl:template>
<xsl:template name="filename">
<xsl:param name="path"/>
<xsl:choose>
<xsl:when test="contains($path, 'target=')">
<xsl:value-of select="substring-after($path, 'target=')"/>
</xsl:when>
<xsl:when test="not(contains($path, '/'))">
<xsl:value-of select="$path"/>
</xsl:when>
<xsl:otherwise>
<xsl:call-template name="filename">
<xsl:with-param name="path" select="substring-after($path, '/')"/>
</xsl:call-template>
</xsl:otherwise>
</xsl:choose>
</xsl:template>
</xsl:stylesheet>

115
doc/fixes.xslt Normal file
View File

@ -0,0 +1,115 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
#
# This file is part of Plinth.
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU Affero General Public License as
# published by the Free Software Foundation, either version 3 of the
# License, or (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU Affero General Public License for more details.
#
# You should have received a copy of the GNU Affero General Public License
# along with this program. If not, see <http://www.gnu.org/licenses/>.
#
-->
<xsl:stylesheet version="1.0"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
<!-- Set output format to Docbook -->
<xsl:output
method="xml"
encoding="utf-8"
indent="yes"
doctype-public="-//OASIS//DTD DocBook XML V4.4//EN"
doctype-system="http://www.docbook.org/xml/4.4/docbookx.dtd"/>
<!-- Copy all nodes and attributes by default -->
<xsl:template match="@*|node()">
<xsl:copy>
<xsl:apply-templates select="@*|node()"/>
</xsl:copy>
</xsl:template>
<!-- Replace / in title with a space -->
<xsl:template match="articleinfo/title/text()">
<xsl:call-template name="clean-title">
<xsl:with-param name="title" select="."/>
</xsl:call-template>
</xsl:template>
<xsl:template name="clean-title">
<xsl:param name="title"/>
<xsl:choose>
<xsl:when test="contains($title, '/')">
<xsl:value-of select="substring-before($title, '/')"/>
<xsl:text> </xsl:text>
<xsl:call-template name="clean-title">
<xsl:with-param name="title" select="substring-after($title, '/')"/>
</xsl:call-template>
</xsl:when>
<xsl:otherwise>
<xsl:value-of select="$title"/>
</xsl:otherwise>
</xsl:choose>
</xsl:template>
<!-- Remove revision history -->
<xsl:template match="revhistory"/>
<!-- Convert all image dimensions from pixels to points -->
<xsl:template match="@width[parent::imagedata]|@depth[parent::imagedata]">
<xsl:attribute name="{name()}">
<xsl:value-of select=". div 2"/>
<xsl:text>pt</xsl:text>
</xsl:attribute>
</xsl:template>
<!-- Convert all image source URLs to relative paths -->
<xsl:template match="@fileref[parent::imagedata]">
<xsl:attribute name="fileref">
<xsl:text>images/</xsl:text>
<xsl:call-template name="filename">
<xsl:with-param name="path" select="."/>
</xsl:call-template>
</xsl:attribute>
</xsl:template>
<!-- Output just the filename from a URL -->
<xsl:template name="filename">
<xsl:param name="path"/>
<xsl:choose>
<xsl:when test="contains($path, 'target=')">
<xsl:value-of select="substring-after($path, 'target=')"/>
</xsl:when>
<xsl:when test="not(contains($path, '/'))">
<xsl:value-of select="$path"/>
</xsl:when>
<xsl:otherwise>
<xsl:call-template name="filename">
<xsl:with-param name="path" select="substring-after($path, '/')"/>
</xsl:call-template>
</xsl:otherwise>
</xsl:choose>
</xsl:template>
<!-- Fix incorrectly output wiki links -->
<xsl:template match="@url[parent::ulink]">
<xsl:attribute name="url">
<xsl:choose>
<xsl:when test="contains(., 'FreedomBox/Manual/')">
<xsl:value-of select="substring-before(., 'FreedomBox/Manual/')"/>
<xsl:value-of select="substring-after(., 'FreedomBox/Manual/')"/>
</xsl:when>
<xsl:otherwise>
<xsl:value-of select="."/>
</xsl:otherwise>
</xsl:choose>
</xsl:attribute>
</xsl:template>
</xsl:stylesheet>

View File

@ -1 +0,0 @@
../HACKING