On Thursday, 31 December 2015 at 06:39:27 UTC, Israel wrote:
This is what hits me the most. Thats why we suggested "user
contributed examples". PHP docs is the only place ive seen
this. What is your stance on this and if you agree, how would
you implement it? How would it work?
I do not agree with comments, but I do agree with making user
What I am envisioning right now is a kind of suggestion box thing
on an individual page, where you can write up a bug report, an
example, a comment, whatever, and have it emailed to me for
further consideration. I'll do a quick fact-check editing then
add it to the page.
Of course, you can also continue to submit pull requests through
github (and I'd encourage this for bigger contributors), but just
emailing your thoughts to me has a lower barrier of entry.
If we do a good job with the actual docs, you won't need
comments. And better yet, you won't have to read through dozens
of old ones to find the thing you need. On PHP, I find the
comments list is too long and of too low of an average quality to
be worth reading most the time.
The other important thing is being able to add new pages with
ease. I just dreamed up this plan while in bed last night: a new
page would be a D file with a huge leading comment and a bunch of
documented unit tests. (Why a regular D file? Because then we can
reference it by its name, it can be listed in the package listing
automatically, and you can actually compile it to test the code
without any extra extraction work!)
A comment at the top of "// just docs: Some Page Title" tells the
generator to format it as a page rather than a normal module
(this means the title in the comment will be used instead of the
module name and it will have a table of contents of text sections
instead of D classes, structs, and other members.)
I'll make a web service where you can upload your .d file and get
an instant preview. This way, you can render it without needing
to figure out how to install my doc generator and build the
website on your own computer. Just submit the form.
Then, if you like it, you can either email the file to me and
I'll take it from there, or submit a pull request to add your
The PR will only need to do:
git checkout -b my_new_file
git add my_new_file.d
git commit my_new_file.d -m 'add my new file!'
No need to edit other macro files, build files, TOC files,
whatever. My infrastructure takes care of that automatically.
(via build **/*.d. It isn't rocket science and it baffles me that
the official D system is so convoluted.)
What do the files look like? Well, I'm still working on nailing
this down, but it is basically a hybrid of markdown and ddoc, but
it does NOT support ddoc's custom macros. First off, I think they
are a mess with everyone defining the same all over (look at
Phobos, it gets confusing) and secondly it makes doing semantic
analysis of the text harder since a ddoc macro is freeform. With
unlimited macros, any $ or comma in the text might be significant
syntax! That's a pain.
And it leads to bugs. Take a look at the References section here:
It says "RFC 4648 - The Base16". The title is actually longer
than that... it just had a comma in it and ddoc thought that
meant end of argument.
There *are* ways to handle this in ddoc, of course, and they
aren't even really hard. I deal with it every week in the TWID
source. But it is just one little example of a bigger problem
that limits how much automatic processing we can do. Not worth it.
Anyway, this is what contributed article file might look like. It
continues to the end of this email:
// just docs: Introduction to my new doc system
This is the intro line.
An intro paragraph. This is seen on the article listing too. Then
leave two blank lines gap for the table of contents.
Now you start writing details. You can have headers, code
examples, and so on like in any other doc.
$(H2 The headers look like ddoc macros)
They translate to the corresponding HTML and are parsed to form a
table of contents which is automatically inserted in the blank
area you left above.
$(H3 You can descend in with headers)
This section would be a sub-section of the H2 above.
$(H2 References and code)
You reference items with $(REF std.xml) and write code with
`markdown style` or
More to come as it develops.
module mydocs.intro; // you give it a D name to refer to in refs
/// you can also include documented unittests as full examples
/// that will be attached. I need to think of some way to
/// reference them in the text. If only D had named unittests!
// this code can actually be compiled with dmd -unittest
// right out of the box to keep your examples working well.
// all done.