diff --git a/LICENSES b/LICENSES index f5db61d4e..4c1329891 100644 --- a/LICENSES +++ b/LICENSES @@ -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]] diff --git a/doc/Makefile b/doc/Makefile index 476d00d8b..bf06f78e8 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -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 . +# -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 $@ $< '%.*%' - sed '1d' $@00 > $@01 - csplit -s -f $@ $@01 '/<\/body>/' - mv $@00 $@ - rm $@01 + perl -pe 'BEGIN {undef $/} s/.*]*>(.*)<\/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 diff --git a/doc/design.mdwn b/doc/design.mdwn deleted file mode 100644 index 2b3c204b3..000000000 --- a/doc/design.mdwn +++ /dev/null @@ -1,50 +0,0 @@ - - -# 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. diff --git a/doc/design/first-connection.mdwn b/doc/design/first-connection.mdwn deleted file mode 100644 index aeca28f29..000000000 --- a/doc/design/first-connection.mdwn +++ /dev/null @@ -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. diff --git a/doc/fetch-images.xslt b/doc/fetch-images.xslt new file mode 100644 index 000000000..480f62d13 --- /dev/null +++ b/doc/fetch-images.xslt @@ -0,0 +1,67 @@ + + + + + + + + + + + + + + + + + + " + + " + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/doc/fixes.xslt b/doc/fixes.xslt new file mode 100644 index 000000000..af9ec4ec9 --- /dev/null +++ b/doc/fixes.xslt @@ -0,0 +1,115 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + pt + + + + + + + images/ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/doc/hacking.mdwn b/doc/hacking.mdwn deleted file mode 120000 index cc8063b39..000000000 --- a/doc/hacking.mdwn +++ /dev/null @@ -1 +0,0 @@ -../HACKING \ No newline at end of file