Re: [piqi] Make `tools.md` better suited for `pandoc -t man` (#30)

[Motiejus Jakštys]

The documentation mangler is done[1], wget --spider does not complain
after these changes, and after some clicking around it seems to look OK.
Now we have these external resources which should stay like that*:

1. /doc/erlang/
2. /doc/piqi-rpc/

And these are now external, but, IMO could be made internal:

3. /doc/faq/
4. /examples/
5. /self-definition/
6. /rationale/

What do you think about including them to the source tree?

Aside: have you ever considered using Sphinx for documentation? It is
quite a good tool, and you should be familiar with it if you are/have
been Python user any time. It is as easy to use for a developer as is
for a user. It especially well does the cross-references and
javascript-based search. We use it in the company all over the place,
for projects involving many different programming languages.

The reason I am asking is that would make my life easier, because all
that ugly sed scripts would not even be necessary. Besides, you could
have free hosting at things like readthedocs.org (with automatic
documentation updates). Also, you can get pretty crazy with CSS in
Sphinx (and readthedocs).. There are many more pros. If you want to, you
could make the whole piqi.org generate-able from a few repos (piqi,
piqi-erlang, piqi-rpc).

Motiejus

[1]:
https://github.com/Motiejus/piqi-deb/blob/motiejus/debian/snapshot/debian/README.source

[*]: Not that I like it; there is just no logical way to include them to
the repository now, unless we have a piqi-doc package which hosts all
piqi documentation, which is a bit overkill sadly.