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
)
``
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.
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.
