Re: Few thoughts about (theoretical) new manual format

On Tue, Apr 1, 2014 at 6:35 AM, Maciej Sobaczewski <msobaczewski@gmail.com> wrote: > Hello guys, > > I know that this subject wasn't discussed for a long time and I fullly > understand that most of you probably doesn't care my opinion on it, but I > would like to write few of my thoughts on proposed several years ago by > Hannes. Just as a suggestions for people who will (or not) develop it in the > future. > > 1) Markdown or other formats: I love markdown and I also think that XML > syntax which we use today is overcomplicated, but... I think that markdown > isn't good solution for our purposes. I consider PHP manual too complicated Did you see http://php.markmail.org/message/savqyv5rbh66beh3 ? I already wrote proof-of-concept XML->markdown converter and the markdown renderer. It had some kinks and quirks left in it, but all these things you say not possible was really possible. Extending the markup, entity magic, and identical hierarchy and generated menus and navigation. The sad thing is... It was running on www.php.net/~hannes That server is however no longer with us so I don't think I have a copy of it :) > Basically, I found XML or something similiar a good solution in our case. > It's extensible, what allows us to easily improve output without changinng > internal files. Maybe we could just simplify it? Make it easier to write and > mantain. As far as I can see docbook isn't developed for a few yars. Maybe > we just could improve it's syntax? Probably people more inventent in > writing/translating docs have some more detailed ideas. They are doing it > almost today, so they should know what can be improved/fixed. Thats just not true at all. There is even a OASIS committee for Docbook, not to mention serious enterprise commitment in the project. We already only use a very small subset of Docbook, and reducing it even more doesn't solve anything. Remember, the rendering time is killing us. Yes, even though it has come down from 36 hours to under a minute, it is still a minute to long. The tricks we do to get the rendering time down to a second still require 15second warmup time (confiugre.php --generate) and we are pretty damn close to our theoretical maximum performance. > > 2) Translations: I think that all of you can agree that big change in our > docs format will be huge problem for doc writers and especially translators. When we change formats the translations would ofcourse be converted at the same time. They would only need to "learn" the new format, but if we pick a anti-format then there isn't anything to learn. > translate such documents, becouse they know that most of programmers know or > should know English. I can see it in my (Polish) team. There are many other ...Translators need to know English yes, thats the only way they can translation our English documentation into their local languages. It is not our call to tell the world to learn English. Far from it. Its fine if we don't translate the documentations into Icelandic, but Spanish, French, German, Japanese, ... of course we should. And any other language people would like to contribute. > ways of better time spending than translating something what has to bee > up-to-date or it's useless. I mean that translators' motivation is already Thats a different topic, and has to do with how we "detect" a change. I've long been against the current way, but lets leave that up to a different thread :) > 3) The other disadvantage of changing our format to something totally else > is obvious. Probably it won't be finished at all, like previous ideas. I have not half-finished something I have taken on yet. And I finsihed the DSSL to XSL work. And I did the XSL to PhD work. And I did the Docbook4 to Docbook5 work...... "Unfortunately" taking care of an infant took more time then I expected, so I haven't finished this yet so it can go through full review... but one day. One day. And no, it will not be "half of the english files converted, and 1/3 in some translation". This is a all-or-nothing type of thing. I am well aware of that. > To summarize, I think that we have to found methods to improve already > existing syntax instead of creating new one. As I told in the beginnig, I must have missed it, what was the concrete suggestion? -Hannes