| 1 |
On 11/26/10 21:18, Zac Medico wrote: |
| 2 |
> On 11/26/2010 08:32 AM, Lionel Orry wrote: |
| 3 |
>> Dear all, |
| 4 |
>> |
| 5 |
>> I just made a try to convert the portage documentation |
| 6 |
>> (http://dev.gentoo.org/~zmedico/portage/doc/) to asciidoc so that it |
| 7 |
>> would be easier to maintain and with a standard layout and style that |
| 8 |
>> is IMHO not bad and makes the doc easier to read. Are you interested? |
| 9 |
>> |
| 10 |
>> I attach the asciidoc sources, a tiny makefile and an already |
| 11 |
>> generated version in the 'portage.chunked' directory. All you need to |
| 12 |
>> generate the doc is 'emerge asciidoc'. |
| 13 |
|
| 14 |
What I have seen of the output looked awesome, the sources look clean. |
| 15 |
|
| 16 |
I noticed that on the index page the table of contents are not as |
| 17 |
detailed as in the current version online. Is that wanted or a |
| 18 |
limitation? If the latter: is that a problem? |
| 19 |
|
| 20 |
On the conversion: did you come across any limitations? |
| 21 |
Anything that you were not able to map 1:1? |
| 22 |
|
| 23 |
|
| 24 |
>> The only issue I had was including several authors, so this part is |
| 25 |
>> commented out. But if we stick to the docbook backend, we can include |
| 26 |
>> a docinfo file that solves the problem. |
| 27 |
>> |
| 28 |
>> Hope you'll find this useful... |
| 29 |
> |
| 30 |
> The asciidoc format seems nice, but personally, I think I prefer docbook |
| 31 |
> since the SGML/XML approach seems more flexible and extensible. |
| 32 |
|
| 33 |
Are you making use of that flexibility anywhere at the moment? If not |
| 34 |
is such use planned for something specific? |
| 35 |
|
| 36 |
In case DocBook is keeping contributions down than cutting away certain |
| 37 |
flexibility to increase contributions could be a good trade-off, too. |
| 38 |
|
| 39 |
|
| 40 |
> Maybe |
| 41 |
> XML isn't quite as easy to read and edit, but it seems like a good |
| 42 |
> trade-off to me. |
| 43 |
|
| 44 |
I migrated the documentation of Layman from DocBook to AsciiDoc recently |
| 45 |
[1], because I noticed that the one reason I never really touched the |
| 46 |
documentation after taking Layman over (besides version upgrades) was |
| 47 |
DocBook. And that despite the fact that I started using AsciiDoc only a |
| 48 |
few months ago (on the enum project [2]). |
| 49 |
|
| 50 |
Best, |
| 51 |
|
| 52 |
|
| 53 |
|
| 54 |
Sebastian |
| 55 |
|
| 56 |
|
| 57 |
[1] |
| 58 |
http://layman.git.sourceforge.net/git/gitweb.cgi?p=layman/layman;a=commitdiff;h=a8eee022c6dc2085d4e37e838ffb45404f77242b |
| 59 |
[2] |
| 60 |
http://git.fedorahosted.org/git/?p=enum.git;a=blob;f=man/enum.1.txt;hb=HEAD |
Archives