Re: [gentoo-portage-dev] portage docbook documentation -> why not asciidoc ?
On Monday, November 29, 2010 18:59:04 Daniel Barkalow wrote: > On Sat, 27 Nov 2010, Zac Medico wrote: > > On 11/27/2010 01:25 AM, Sebastian Pipping wrote: > > > In case DocBook is keeping contributions down than cutting away certain > > > flexibility to increase contributions could be a good trade-off, too. > > > > I'm not sure that docbook represents a significant barrier in this > > respect. It's hard to speculate. Maybe if we had a survey sampling the > > opinions of a broad spectrum of open-source developers, then we'd have > > more to go on. > > My impression from git development is that, with asciidoc, we got a lot of > documentation patches from users who read the documentation, found that it > was inaccurate or unclear, and were able to propose corrections based on > their observation of the actual behavior. I believe we also got > documentation of previously undocumented functionality, written by people > who had found out how to use it from some other source after failing to > find it mentioned in the documentation. I suspect that docbook is too high > a barrier for some people when asciidoc wouldn't be; the question is > really whether any of these people are the audience for portage > documentation. all of the user-facing documentation is in the man pages. all of the docbook pages are generally more internal stuff. so any of the corrections you discuss i think would be files under man/ and not doc/. -mike signature.asc Description: This is a digitally signed message part.
Re: [gentoo-portage-dev] portage docbook documentation -> why not asciidoc ?
On Sat, 27 Nov 2010, Zac Medico wrote: > On 11/27/2010 01:25 AM, Sebastian Pipping wrote: > > In case DocBook is keeping contributions down than cutting away certain > > flexibility to increase contributions could be a good trade-off, too. > > I'm not sure that docbook represents a significant barrier in this > respect. It's hard to speculate. Maybe if we had a survey sampling the > opinions of a broad spectrum of open-source developers, then we'd have > more to go on. My impression from git development is that, with asciidoc, we got a lot of documentation patches from users who read the documentation, found that it was inaccurate or unclear, and were able to propose corrections based on their observation of the actual behavior. I believe we also got documentation of previously undocumented functionality, written by people who had found out how to use it from some other source after failing to find it mentioned in the documentation. I suspect that docbook is too high a barrier for some people when asciidoc wouldn't be; the question is really whether any of these people are the audience for portage documentation. -Daniel *This .sig left intentionally blank*
Re: [gentoo-portage-dev] portage docbook documentation -> why not asciidoc ?
On Sat, Nov 27, 2010 at 10:50 PM, Mike Frysinger wrote: > On Saturday, November 27, 2010 16:39:04 Alec Warner wrote: >> On Sat, Nov 27, 2010 at 6:53 AM, Zac Medico wrote: >> > As it is, I'm fairly comfortable with docbook. Now you want me to learn >> > a new format, with possible drawbacks, in order to try and draw in some >> > contributions that may never happen? >> >> Here is where I would look for data. Are there pending contributions? >> I have not seen anyone on this list specifically say "I'd write some >> documentation if it was not in docbook." I have had issues (years >> ago) getting vapier to write documentation; but I assumed that was >> because he hated writing docs and he contributed documentation after a >> while. > > not sure where you're going with this, but i'm the one who started the doc/ > dir and introduced the docbook system. obviously i have no problem with it > and would rather see real examples of people who are being impeded by it > rather than yet another "omg we need to switch to this awesome new format > because it is so awesome". > -mike > Hi Mike, at the beginning, I've just made a try and see if it would be feasible, then I decided to suggest the portage team about it, that's all. As I said before, if the majority of relevant people are not interested and want to stay with a docbook source, that's totally fine. I never meant to change habits neither do I pretend that asciidoc is awesome. It was simply a suggestion, in case you did not know it. I also understand that it's not good to change formats all the time.If docbook is well established as the reference tool for you to make docs, then please, keep the docbook format and just forget about the discussion. As an aside note, that would be a bit more pleasant to read if the current doc had a bit of css styling. Would you be against that ? I am not a designer at all, but I can still suggest a css for docbook, unless some Gentoo project already suggests one. Best regards, Lionel
Re: [gentoo-portage-dev] portage docbook documentation -> why not asciidoc ?
On Sat, Nov 27, 2010 at 1:50 PM, Mike Frysinger wrote: > On Saturday, November 27, 2010 16:39:04 Alec Warner wrote: >> On Sat, Nov 27, 2010 at 6:53 AM, Zac Medico wrote: >> > As it is, I'm fairly comfortable with docbook. Now you want me to learn >> > a new format, with possible drawbacks, in order to try and draw in some >> > contributions that may never happen? >> >> Here is where I would look for data. Are there pending contributions? >> I have not seen anyone on this list specifically say "I'd write some >> documentation if it was not in docbook." I have had issues (years >> ago) getting vapier to write documentation; but I assumed that was >> because he hated writing docs and he contributed documentation after a >> while. > > not sure where you're going with this, but i'm the one who started the doc/ > dir and introduced the docbook system. obviously i have no problem with it > and would rather see real examples of people who are being impeded by it > rather than yet another "omg we need to switch to this awesome new format > because it is so awesome". > -mike > I'm saying you should write more docs! But we agree on the other point ;)
Re: [gentoo-portage-dev] portage docbook documentation -> why not asciidoc ?
On Saturday, November 27, 2010 16:39:04 Alec Warner wrote: > On Sat, Nov 27, 2010 at 6:53 AM, Zac Medico wrote: > > As it is, I'm fairly comfortable with docbook. Now you want me to learn > > a new format, with possible drawbacks, in order to try and draw in some > > contributions that may never happen? > > Here is where I would look for data. Are there pending contributions? > I have not seen anyone on this list specifically say "I'd write some > documentation if it was not in docbook." I have had issues (years > ago) getting vapier to write documentation; but I assumed that was > because he hated writing docs and he contributed documentation after a > while. not sure where you're going with this, but i'm the one who started the doc/ dir and introduced the docbook system. obviously i have no problem with it and would rather see real examples of people who are being impeded by it rather than yet another "omg we need to switch to this awesome new format because it is so awesome". -mike signature.asc Description: This is a digitally signed message part.
Re: [gentoo-portage-dev] portage docbook documentation -> why not asciidoc ?
On Sat, Nov 27, 2010 at 6:53 AM, Zac Medico wrote: > On 11/27/2010 01:25 AM, Sebastian Pipping wrote: >> On 11/26/10 21:18, Zac Medico wrote: >>> The asciidoc format seems nice, but personally, I think I prefer docbook >>> since the SGML/XML approach seems more flexible and extensible. >> >> Are you making use of that flexibility anywhere at the moment? If not >> is such use planned for something specific? > > Honestly, I don't know. > >> In case DocBook is keeping contributions down than cutting away certain >> flexibility to increase contributions could be a good trade-off, too. > > I'm not sure that docbook represents a significant barrier in this > respect. It's hard to speculate. Maybe if we had a survey sampling the > opinions of a broad spectrum of open-source developers, then we'd have > more to go on. In general I don't see docbook as a problem. If I file a portage bug and say something needs to be changed or documented then attaching plain text additions is usually sufficient for inclusion. The bigger problem portage faces is that very few people actually know enough about how it works and this leaves only a few people who can actually write (or verify) that documentation is correct. > > As it is, I'm fairly comfortable with docbook. Now you want me to learn > a new format, with possible drawbacks, in order to try and draw in some > contributions that may never happen? Here is where I would look for data. Are there pending contributions? I have not seen anyone on this list specifically say "I'd write some documentation if it was not in docbook." I have had issues (years ago) getting vapier to write documentation; but I assumed that was because he hated writing docs and he contributed documentation after a while. > -- > Thanks, > Zac > >
Re: [gentoo-portage-dev] portage docbook documentation -> why not asciidoc ?
On 11/27/2010 01:25 AM, Sebastian Pipping wrote: > On 11/26/10 21:18, Zac Medico wrote: >> The asciidoc format seems nice, but personally, I think I prefer docbook >> since the SGML/XML approach seems more flexible and extensible. > > Are you making use of that flexibility anywhere at the moment? If not > is such use planned for something specific? Honestly, I don't know. > In case DocBook is keeping contributions down than cutting away certain > flexibility to increase contributions could be a good trade-off, too. I'm not sure that docbook represents a significant barrier in this respect. It's hard to speculate. Maybe if we had a survey sampling the opinions of a broad spectrum of open-source developers, then we'd have more to go on. As it is, I'm fairly comfortable with docbook. Now you want me to learn a new format, with possible drawbacks, in order to try and draw in some contributions that may never happen? -- Thanks, Zac
Re: [gentoo-portage-dev] portage docbook documentation -> why not asciidoc ?
On 11/27/10 13:27, Lionel Orry wrote: > [Lionel] In fact you can customize the toc level with a 'toclevel' > attribute on the command-line, see the Makefile. I did several tries > but you can get the same level as the original doc with '-a > toclevels=4' if I remember well. In short, it's not a problem. I see, thanks. > But one thing I don't know, is that whether that doc > asks for external contributions or is kept as an internal reference > and should only be taken care of by the devs. That would mean it stays unnecessarily hard for new devs to join if I understand your point correctly. Best, Sebastian
Re: [gentoo-portage-dev] portage docbook documentation -> why not asciidoc ?
On Sat, Nov 27, 2010 at 10:25 AM, Sebastian Pipping wrote: > On 11/26/10 21:18, Zac Medico wrote: >> On 11/26/2010 08:32 AM, Lionel Orry wrote: >>> Dear all, >>> >>> I just made a try to convert the portage documentation >>> (http://dev.gentoo.org/~zmedico/portage/doc/) to asciidoc so that it >>> would be easier to maintain and with a standard layout and style that >>> is IMHO not bad and makes the doc easier to read. Are you interested? >>> >>> I attach the asciidoc sources, a tiny makefile and an already >>> generated version in the 'portage.chunked' directory. All you need to >>> generate the doc is 'emerge asciidoc'. > > What I have seen of the output looked awesome, the sources look clean. [Lionel] Thanks, but please note that I did not customisation to the standard style shipped with asciidoc. This default css is quite good most of the time, but it's still interesting to know that a customization layer is very easy to add, for example to get closer to a gentoo style. > > I noticed that on the index page the table of contents are not as > detailed as in the current version online. Is that wanted or a > limitation? If the latter: is that a problem? [Lionel] In fact you can customize the toc level with a 'toclevel' attribute on the command-line, see the Makefile. I did several tries but you can get the same level as the original doc with '-a toclevels=4' if I remember well. In short, it's not a problem. > > On the conversion: did you come across any limitations? > Anything that you were not able to map 1:1? > [Lionel] Indeed, a few things : 1. I must investigate how to include several tocs (one per each part) as the original doc does. I think this is a matter of docbook backend customization. Again, a customization layer is easy to add, we just have to create a 'docbook.conf' file in the same directory as the input 'portage.txt' file and only include overrides in it. I will do it your team thinks it's worth looking deeper at switching to asciidoc. 2. Only 5 section levels are allowed by asciidoc, most of the time they are really enough, but it seems the portage documentation uses many more nested levels (7 or maybe 8). So I tricked a bit by replacing these section titles by stylized paragraphs (strong for level 6 and emphasized (italic) for level 7. I can't remember if there were level 8, if it was the case, I think I used a normal paragraph. This implies a loss of semantics and not-that-good look and feel in my opinion, but there's a good point for asciidoc: independently of the backend/tool used to write a technical documentation, I feel like using more than 5 levels of nesting shows that the doc has a problem. It should either be restructured, or split in several documentations. It's hard to follow the logic line of a doc that uses so many nested levels. That's a personal opinion, and I don't consider myself a good doc writer either. One should note that sections is not the only way to structure the doc. Lists (ordered, itemized and labeled (definition lists)) help a lot in doing so, and both asciidoc and docbook allow to inserts anchors on such elements so the cross-referencing is possible. 3. The multiple author issue explained below. One solution is already given below, I will look at it deeper if it's not a loss of time. > >>> The only issue I had was including several authors, so this part is >>> commented out. But if we stick to the docbook backend, we can include >>> a docinfo file that solves the problem. >>> >>> Hope you'll find this useful... >> >> The asciidoc format seems nice, but personally, I think I prefer docbook >> since the SGML/XML approach seems more flexible and extensible. > > Are you making use of that flexibility anywhere at the moment? If not > is such use planned for something specific? > > In case DocBook is keeping contributions down than cutting away certain > flexibility to increase contributions could be a good trade-off, too. [Lionel] I can only agree with you about that. Docbook is certainly a very good standard, but writing xml does scare people and it is probably a blocker for contributions. asciidoc (or other similar formats like RST and such) helps contributions, it's like editing a plain README. But one thing I don't know, is that whether that doc asks for external contributions or is kept as an internal reference and should only be taken care of by the devs. > > >> Maybe >> XML isn't quite as easy to read and edit, but it seems like a good >> trade-off to me. > > I migrated the documentation of Layman from DocBook to AsciiDoc recently > [1], because I noticed that the one reason I never really touched the > documentation after taking Layman over (besides version upgrades) was > DocBook. And that despite the fact that I started using AsciiDoc only a > few months ago (on the enum project [2]). [Lionel] Thanks for sharing your ideas! In my case, I already helped the waf project to migrate from docbook to asciidoc and its maintainer is quite happy
Re: [gentoo-portage-dev] portage docbook documentation -> why not asciidoc ?
On 11/26/10 21:18, Zac Medico wrote: > On 11/26/2010 08:32 AM, Lionel Orry wrote: >> Dear all, >> >> I just made a try to convert the portage documentation >> (http://dev.gentoo.org/~zmedico/portage/doc/) to asciidoc so that it >> would be easier to maintain and with a standard layout and style that >> is IMHO not bad and makes the doc easier to read. Are you interested? >> >> I attach the asciidoc sources, a tiny makefile and an already >> generated version in the 'portage.chunked' directory. All you need to >> generate the doc is 'emerge asciidoc'. What I have seen of the output looked awesome, the sources look clean. I noticed that on the index page the table of contents are not as detailed as in the current version online. Is that wanted or a limitation? If the latter: is that a problem? On the conversion: did you come across any limitations? Anything that you were not able to map 1:1? >> The only issue I had was including several authors, so this part is >> commented out. But if we stick to the docbook backend, we can include >> a docinfo file that solves the problem. >> >> Hope you'll find this useful... > > The asciidoc format seems nice, but personally, I think I prefer docbook > since the SGML/XML approach seems more flexible and extensible. Are you making use of that flexibility anywhere at the moment? If not is such use planned for something specific? In case DocBook is keeping contributions down than cutting away certain flexibility to increase contributions could be a good trade-off, too. > Maybe > XML isn't quite as easy to read and edit, but it seems like a good > trade-off to me. I migrated the documentation of Layman from DocBook to AsciiDoc recently [1], because I noticed that the one reason I never really touched the documentation after taking Layman over (besides version upgrades) was DocBook. And that despite the fact that I started using AsciiDoc only a few months ago (on the enum project [2]). Best, Sebastian [1] http://layman.git.sourceforge.net/git/gitweb.cgi?p=layman/layman;a=commitdiff;h=a8eee022c6dc2085d4e37e838ffb45404f77242b [2] http://git.fedorahosted.org/git/?p=enum.git;a=blob;f=man/enum.1.txt;hb=HEAD
Re: [gentoo-portage-dev] portage docbook documentation -> why not asciidoc ?
On 11/26/2010 12:37 PM, Lionel Orry wrote: > The fact is, asciidoc does generate native docbook output. The result > I gave was made using docbook-xsl-stylesheets and a css file. So you > wouldn't loose the docbook flexibility then... Hmm, do it's like an extra translation layer on top of docbook? For ease in reading/editing, I think that I'd prefer to use some type of automated editing tool that to add an additional layer of markup. -- Thanks, Zac
Re: [gentoo-portage-dev] portage docbook documentation -> why not asciidoc ?
The fact is, asciidoc does generate native docbook output. The result I gave was made using docbook-xsl-stylesheets and a css file. So you wouldn't loose the docbook flexibility then... My 2 cents. It's up to you, of course. Lionel On Fri, Nov 26, 2010 at 9:18 PM, Zac Medico wrote: > On 11/26/2010 08:32 AM, Lionel Orry wrote: >> Dear all, >> >> I just made a try to convert the portage documentation >> (http://dev.gentoo.org/~zmedico/portage/doc/) to asciidoc so that it >> would be easier to maintain and with a standard layout and style that >> is IMHO not bad and makes the doc easier to read. Are you interested? >> >> I attach the asciidoc sources, a tiny makefile and an already >> generated version in the 'portage.chunked' directory. All you need to >> generate the doc is 'emerge asciidoc'. >> >> The only issue I had was including several authors, so this part is >> commented out. But if we stick to the docbook backend, we can include >> a docinfo file that solves the problem. >> >> Hope you'll find this useful... > > The asciidoc format seems nice, but personally, I think I prefer docbook > since the SGML/XML approach seems more flexible and extensible. Maybe > XML isn't quite as easy to read and edit, but it seems like a good > trade-off to me. > -- > Thanks, > Zac > >
Re: [gentoo-portage-dev] portage docbook documentation -> why not asciidoc ?
On 11/26/2010 08:32 AM, Lionel Orry wrote: > Dear all, > > I just made a try to convert the portage documentation > (http://dev.gentoo.org/~zmedico/portage/doc/) to asciidoc so that it > would be easier to maintain and with a standard layout and style that > is IMHO not bad and makes the doc easier to read. Are you interested? > > I attach the asciidoc sources, a tiny makefile and an already > generated version in the 'portage.chunked' directory. All you need to > generate the doc is 'emerge asciidoc'. > > The only issue I had was including several authors, so this part is > commented out. But if we stick to the docbook backend, we can include > a docinfo file that solves the problem. > > Hope you'll find this useful... The asciidoc format seems nice, but personally, I think I prefer docbook since the SGML/XML approach seems more flexible and extensible. Maybe XML isn't quite as easy to read and edit, but it seems like a good trade-off to me. -- Thanks, Zac
[gentoo-portage-dev] portage docbook documentation -> why not asciidoc ?
Dear all, I just made a try to convert the portage documentation (http://dev.gentoo.org/~zmedico/portage/doc/) to asciidoc so that it would be easier to maintain and with a standard layout and style that is IMHO not bad and makes the doc easier to read. Are you interested? I attach the asciidoc sources, a tiny makefile and an already generated version in the 'portage.chunked' directory. All you need to generate the doc is 'emerge asciidoc'. The only issue I had was including several authors, so this part is commented out. But if we stick to the docbook backend, we can include a docinfo file that solves the problem. Hope you'll find this useful... Kind regards, Lionel portage_doc_asciidoc.tar.gz Description: GNU Zip compressed data
