1 |
On 25 September 2013 10:30, Tom Wijsman <TomWij@g.o> wrote: |
2 |
|
3 |
> If I want to browse all documentation with a browser, just going to |
4 |
> something like file:///usr/share/doc and read them all in the same |
5 |
> style (using an extension like Stylebot or so); then it would be neat |
6 |
> if Gentoo could bring them down to the same format to me, instead of |
7 |
> that I would need to do local conversion or use multiple viewers for |
8 |
> what could be in one canonical place. |
9 |
> |
10 |
|
11 |
|
12 |
How about doing it "Out of band" by a yet-to-exist gentoo tool that can |
13 |
create a format to the users liking on demand? |
14 |
|
15 |
I mean, whatever way you look at it, such a tool *MUST* exist to simply |
16 |
format the markdown to X-Format anyway. |
17 |
|
18 |
So why do this during ebuild phases? Why not have a tool that handles this? |
19 |
|
20 |
This greatly simplifies the problem that will transpire if we want to |
21 |
support more than one markdown standard, namely, an increased bulk of |
22 |
dependencies. |
23 |
|
24 |
As to identifying what standard to use for a given markdown document, I |
25 |
feel trying to do that automatically will result in sorrow, as will trying |
26 |
to develop one tool that handles all formats in the same document. |
27 |
|
28 |
I think maybe we could support a metafile of some description in the |
29 |
doc/<$pn-$pv>/ directory that describes a list of documents and the |
30 |
relevant format decoder to use for that document. |
31 |
|
32 |
This approach means we can do this for more than just markdown documents, |
33 |
and we can have support of extension-free files that happen to be in RST |
34 |
format instead, or ascii-doc, or whatever, ie: |
35 |
|
36 |
in /doc/$P/formats.meta |
37 |
README.md : markdown/gfm |
38 |
|
39 |
and then any of our tools can translate on demand to the format needed: |
40 |
|
41 |
less $PATH/README.md |
42 |
|
43 |
^ could even be hooked to discover formats.meta and run the content through |
44 |
a ANSI formatter to translate bold indications into escape codes. |
45 |
|
46 |
And the same tool could be used as a backend for whatever web-browser |
47 |
centric documentation viewer we provide to render the files as html, or |
48 |
even do things like |
49 |
|
50 |
gentoo-fm $PATH/README.md --formatter pdf > /tmp/doc.pdf && okular |
51 |
/tmp/doc.pdf |
52 |
|
53 |
In the event somebody wants to read a simple markdown document as PDF. |
54 |
|
55 |
( This also has the benefits of not necessarily adding a large amount of |
56 |
cruft to doc/ for people who don't need the documentation, and means they |
57 |
wont have to rebuild the package *JUST* to get documentation in a different |
58 |
format ) |
59 |
|
60 |
|
61 |
TL;DR - We can provide a tool, it doesn't have to be locked in to the |
62 |
ebuild phase to be useful, and could be more useful to be seperate of |
63 |
ebuild systems, with ebuild systems only providing minimal amounts of |
64 |
context to help a tool know how to process the document. |
65 |
|
66 |
|
67 |
|
68 |
|
69 |
|
70 |
-- |
71 |
Kent |