On Jun 16, 2014, at 8:27 AM, Maciej Sobaczewski <sobak@php.net> wrote:
Maybe if wiki can be updated so it understands markdown we can revist
this? Although I certainly don't see that happening in the near
future.
Thanks, Chris
There are some plugins and one is quite promising but currently it
doesn't seem to be stable enough :( I'd love to see such change but it's not so easy to do.
It’s great to see you merging and expanding the two HOWTO documents,
something that’s been needed for several years now! Excellent work :)
I'm glad you find this idea useful.
As for the markup discussion, why not DocBook? Basically, replace this:
http://doc.php.net/dochowto/
Originally (IIRC) the idea was to use the wiki as a draft that’d later
end up as a dochowto rewrite in DocBook, but of course that plan didn’t
work out. DocBook is more complicated (especially for developing a draft)
but it’d match the PHP documentation.
Just a thought, I’d rather not interfere and stall the work here but
figured it’s worth mentioning.
I'm not tied to one, specific format. I just wanted to focus on content first, because I was afraid it will become another abandoned project. Obviously, every solution has advantages and disadvantages:
Markdown
+ easy to edit = more contributors (I hope)
+ popular and widely-used syntax
+ we have Github utilities if we put it in web-doc, so mainly PRs
+ we have real VCS
- requires additional infrastructure, so next thing to maintain; it should be really simple, but it is another tool nonetheless
- inconsistency - another format apart from wiki and DocBook
DocBook
+ we already have all needed tools and setup
+ we have real VCS
- it's harder to understand this format for beginners, however, manual contributors really should understand it...
- placed in SVN - probably I'm not the only person who doesn't like working with that VCS = less contributors? I consider it as one of the reasons why old howto became so outdated.
Wiki
+ the easiest way to contribute
- syntax is awful
- versioning is almost unusable
As I told earlier, I see absolutely no problem in rewritting existing content into new format. We just have to make a decision.
Regards,
Philip
Thanks,
Maciej