On Sat, Aug 10, 2013 at 1:15 PM, Levi Morrison <morrison.l...@gmail.com> wrote: > After looking at what Hannes proposed, I think it is simple and fairly > usable. I see potential parsing issues in the synopsis section, though. The > code portion of that section should be marked somehow, perhaps with: > > ``php-synopsis > > int function strpos( > string $haystack, > mixed $needle, > int $offset = 0 > ) > ``
Maybe. We'll see when we start writing the format-to-html engine. I don't want any extra characters or stuff if we don't need it. > However, I agree that writing custom markdown is quite pointless when we > could use rst. I'm not sold on that format either; I'm just saying that if > we are going to switch from docbook we need something stable. Rolling our > own sounds like a bad idea. Please convert that sample page to rST. Talk is cheap and we can bikeshed all we want for the fun of it. To make something happen however I need you guys to create an example of the strpos page using your "I wish we used <insert-format-here>" :) Keep in mind, no matter what format we choose we do need to roll our own engine. > It would also be a big transition from docbook to another format. We'd > definitely need a translation tool to help us. I'm not sure what is out > there, but I can definitely say what is not out there: a docbook to > our-custom-markdown formatter. That's another thing to keep in mind. Any off-the-shelf docbook->ascidoc/rST/markdown/whatever is not going to work anyway, so it doesn't matter what is out there :) As for translation tooling - yes, we'd need to find something, not matter how the format winds up. We have for over a decade used.. none. We've had revision numbers, thats it. Recently the OE has done a great job - the new format would greatly simplify that tool too. So it doesn't worry me at all :) -Hannes
