Asciidoc, an alternative for documentation

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
35 messages Options
12
Reply | Threaded
Open this post in threaded view
|

Asciidoc, an alternative for documentation

Boost - Dev mailing list
I've been experimenting with Asciidoc-based documentation, using
Boost.Assert as my guinea pig. The good thing about Asciidoc is that Github
shows a preview and you can edit it directly on github.com. This is how the
source looks there:

https://github.com/boostorg/assert/blob/feature/asciidoc/doc/index.adoc
https://github.com/boostorg/assert/blob/feature/asciidoc/doc/assert.adoc
https://github.com/boostorg/assert/blob/feature/asciidoc/doc/current_function.adoc

This is how the generated HTML documentation looks, using the default
stylesheet, without any customizations on my part:

https://rawgit.com/boostorg/assert/feature/asciidoc/doc/html/assert.html

And this is how the generated PDF looks:

http://pdimov.com/tmp/assert.pdf

The tool that produces these is Asciidoctor, http://asciidoctor.org/ .


_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Asciidoc, an alternative for documentation

Boost - Dev mailing list
2017-06-06 0:00 GMT-03:00 Peter Dimov via Boost <[hidden email]>:

> This is how the generated HTML documentation looks, using the default
> stylesheet, without any customizations on my part:
>
> https://rawgit.com/boostorg/assert/feature/asciidoc/doc/html/assert.html
>

I've converted all of Boost.Http documentation to asciidoc. I don't intend
to use QuickBook/BoostBook again. Too much NIH syndrome and too much
inconvenient.

I use the following options to generate the HTML:

asciidoctor -a toc=left -a toclevels=3 -a sectnums -a sectnumlevels=4
http.adoc

And the following to generate the ePUB:

asciidoctor -b docbook5 http.adoc
pandoc -f docbook http.xml -o http.epub

I was considering paying someone to design a Boost-like theme and the
opened the Boost.Asio documentation. I changed my mind. There is no reason
somebody would like to mirror this theme.

It's infinitely easier to write documentation using asciidoc, and this is a
plus also to receive contributions. Nobody outside Boost know how to get
boostbook up and ready to generate HTML, PDF and ePUB.

Also, asciidoc was designed to make syntactic elements directly mirror
docbook semantics. So you have great Docbook output with a syntax that is
as pleasant to use as MarkDown.

Also, I've found many different ways to generate PDF using asciidoc. All of
them are pretty different when you compare the output of each process. Just
noting in case you didn't like this one generated PDF.

Have fun playing with asciidoc.

--
Vinícius dos Santos Oliveira
https://vinipsmaker.github.io/

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Asciidoc, an alternative for documentation

Boost - Dev mailing list
On 6/5/2017 11:34 PM, Vinícius dos Santos Oliveira via Boost wrote:

> 2017-06-06 0:00 GMT-03:00 Peter Dimov via Boost <[hidden email]>:
>
>> This is how the generated HTML documentation looks, using the default
>> stylesheet, without any customizations on my part:
>>
>> https://rawgit.com/boostorg/assert/feature/asciidoc/doc/html/assert.html
>>
>
> I've converted all of Boost.Http documentation to asciidoc. I don't intend
> to use QuickBook/BoostBook again. Too much NIH syndrome and too much
> inconvenient.

Using quickbook has always appeared easy to me. Generating html and pdf
doc from quickbook source involves a number of steps that need to be
correctly setup via a jamfile, and I think this is what always appears
hard to others.

I am certainly not against other methods of writing Boost documentation
and will look at asciidoc. But I did want to point out that I do not
think the issue with quickbook is really the quickbook syntax itself.
Others of course may well disagree with this assessment.

>
> I use the following options to generate the HTML:
>
> asciidoctor -a toc=left -a toclevels=3 -a sectnums -a sectnumlevels=4
> http.adoc
>
> And the following to generate the ePUB:
>
> asciidoctor -b docbook5 http.adoc
> pandoc -f docbook http.xml -o http.epub
>
> I was considering paying someone to design a Boost-like theme and the
> opened the Boost.Asio documentation. I changed my mind. There is no reason
> somebody would like to mirror this theme.
>
> It's infinitely easier to write documentation using asciidoc, and this is a
> plus also to receive contributions. Nobody outside Boost know how to get
> boostbook up and ready to generate HTML, PDF and ePUB.
>
> Also, asciidoc was designed to make syntactic elements directly mirror
> docbook semantics. So you have great Docbook output with a syntax that is
> as pleasant to use as MarkDown.
>
> Also, I've found many different ways to generate PDF using asciidoc. All of
> them are pretty different when you compare the output of each process. Just
> noting in case you didn't like this one generated PDF.
>
> Have fun playing with asciidoc.
>



_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Asciidoc, an alternative for documentation

Boost - Dev mailing list
On Tue, Jun 6, 2017 at 7:10 AM, Edward Diener via Boost
<[hidden email]> wrote:
> On 6/5/2017 11:34 PM, Vinícius dos Santos Oliveira via Boost wrote:
>>
>> 2017-06-06 0:00 GMT-03:00 Peter Dimov via Boost <[hidden email]>:
>>
>>> This is how the generated HTML documentation looks, using the default
>>> stylesheet, without any customizations on my part:
>>>
>>> https://rawgit.com/boostorg/assert/feature/asciidoc/doc/html/assert.html

Looks nice. I am not familiar with asciidoc...

* Does ascii interface with Doxygen? For example, can you embed in the
asciidoc output a reference section generated by Doxygen and have
hyperlinks in between the ascidoc and Doxygen sections? (Similar to
Quickbook [xinclude ...].)

* Does asciidoc allow to show code snips marked in an external source
file? For example, to show example code snips in Quickbook using
[import <file-name>] and then [abc], where //[abc ... //] are used as
markers in file-name.

> Using quickbook has always appeared easy to me. Generating html and pdf doc
> from quickbook source involves a number of steps that need to be correctly
> setup via a jamfile, and I think this is what always appears hard to others.

This is my experience as well. For example, if there was a
"pre-compiled" distributable of Quickbook that did not require to
download Boost and did not use BJam (as least not require to the users
to use BJam directly), Quickbook would be easier to use.

--Lorenzo

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Asciidoc, an alternative for documentation

Boost - Dev mailing list
2017-06-06 12:03 GMT-03:00 Lorenzo Caminiti via Boost <[hidden email]
>:

> Looks nice. I am not familiar with asciidoc...
>
> * Does ascii interface with Doxygen? For example, can you embed in the
> asciidoc output a reference section generated by Doxygen and have
> hyperlinks in between the ascidoc and Doxygen sections? (Similar to
> Quickbook [xinclude ...].)
>

asciidoc was designed to support DocBook semantics. So, by converting the
file to DocBook XML, you shouldn't loss any information from the
documentation. If you can somehow interface DocBook XML and Doxygen, this
should be doable.

You can use a passthrough block in asciidoc syntax to directly write in
DocBook XML if needed: http://asciidoctor.org/docs/user-manual/#pass-blocks

* Does asciidoc allow to show code snips marked in an external source
> file? For example, to show example code snips in Quickbook using
> [import <file-name>] and then [abc], where //[abc ... //] are used as
> markers in file-name.
>


   -
   http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#source-code
   - http://asciidoctor.org/docs/user-manual/#listing-blocks


I take a long time to answer, but I'm sure you can get quick answers
directly in the asciidoc spaces.


--
Vinícius dos Santos Oliveira
https://vinipsmaker.github.io/

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Asciidoc, an alternative for documentation

Boost - Dev mailing list
In reply to this post by Boost - Dev mailing list
On Tue, Jun 6, 2017 at 8:03 AM, Lorenzo Caminiti via Boost
<[hidden email]> wrote:
> * Does ascii interface with Doxygen? For example, can you embed in the
> asciidoc output a reference section generated by Doxygen and have
> hyperlinks in between the ascidoc and Doxygen sections? (Similar to
> Quickbook [xinclude ...].)

I think the toolchain for Doxygen plus Asciidoc would look like this:

    (header files) -> XML; using Doxygen

    XML -> Asciidoc; using xsltproc

You would need to write an .xslt program to perform the translation
from XML to asciidoc. It might look like this:

<https://github.com/vinniefalco/docca/blob/master/include/docca/doxygen.xsl>

(The .xsl file linked above converts XML into Quickbook).

Thanks

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Asciidoc, an alternative for documentation

Boost - Dev mailing list
In reply to this post by Boost - Dev mailing list
On Tue, Jun 6, 2017 at 11:03 AM, Lorenzo Caminiti via Boost
<[hidden email]> wrote:

> * Does asciidoc allow to show code snips marked in an external source
> file? For example, to show example code snips in Quickbook using
> [import <file-name>] and then [abc], where //[abc ... //] are used as
> markers in file-name.

This is the QuickBook feature I would miss. I've used that heavily to
ensure that the code embedded in the documentation is code that
actually builds and runs, without having to remember to (re-)paste
updates into the document source.

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Asciidoc, an alternative for documentation

Boost - Dev mailing list
On Fri, Oct 6, 2017 at 11:21 AM, Nat Goodspeed via Boost <
[hidden email]> wrote:

> On Tue, Jun 6, 2017 at 11:03 AM, Lorenzo Caminiti via Boost
> <[hidden email]> wrote:
>
> > * Does asciidoc allow to show code snips marked in an external source
> > file? For example, to show example code snips in Quickbook using
> > [import <file-name>] and then [abc], where //[abc ... //] are used as
> > markers in file-name.
>
> This is the QuickBook feature I would miss. I've used that heavily to
> ensure that the code embedded in the documentation is code that
> actually builds and runs, without having to remember to (re-)paste
> updates into the document source.
>

The answer is still yes asciidoctor supports that. Not only that.. It
supports it in a more modular and flexible way than Quickbook.


--
-- Rene Rivera
-- Grafik - Don't Assume Anything
-- Robot Dreams - http://robot-dreams.net
-- rrivera/acm.org (msn) - grafikrobot/aim,yahoo,skype,efnet,gmail

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Asciidoc, an alternative for documentation

Boost - Dev mailing list
In reply to this post by Boost - Dev mailing list
On 6/6/17 7:10 AM, Edward Diener via Boost wrote:
> On 6/5/2017 11:34 PM, Vinícius dos Santos Oliveira via Boost wrote:
>
> Using quickbook has always appeared easy to me. Generating html and pdf
> doc from quickbook source involves a number of steps that need to be
> correctly setup via a jamfile, and I think this is what always appears
> hard to others.

Right.  I skip the Jamfile and use a simple shell script/make file.
maybe about 10 lines.

Given that asciidoc generates docbook files, it's an easy fit into boost
workflow.  It's just e boostbook -> docbook step that get's skipped.
This step isn't all that essential anyway.

Robert Ramey

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Asciidoc, an alternative for documentation

Boost - Dev mailing list
In reply to this post by Boost - Dev mailing list

>> * Does asciidoc allow to show code snips marked in an external source
>> file? For example, to show example code snips in Quickbook using
>> [import <file-name>] and then [abc], where //[abc ... //] are used as
>> markers in file-name.
>
> This is the QuickBook feature I would miss. I've used that heavily to
> ensure that the code embedded in the documentation is code that
> actually builds and runs, without having to remember to (re-)paste
> updates into the document source.

I too have been playing with radically different methods of generating
documentation for Outcome v2, seeing as people panned the v1 Outcome
documentation.

This is bleeding edge stuff i.e. it currently segfaults a lot, but it is
getting there. It uses Hugo to compile the Markdown source files into
HTML via a Travis per-commit job. Standardese may - once Jonathan fixes
the bugs - generate the reference API docs in Markdown from doxygen
marked up C++ source files using libclang.

If we can get it working, it'll be a whole new age of "easy" for writing
docs for complex C++ codebases, and moreover one which finally can parse
the worst possible C++ metaprogramming without blinking because anything
clang can parse can be documented. You literally run just two build
tools, both easily executed from Travis, and push the changes to
gh-pages on Github. Changing documentation is as easy as modifying the
Markdown source or the doxygen format comment section in the relevant
header, git commit and git push. Hugo generates the syntax highlighting,
the wiki linking, the search index and everything else. Oh, and it looks
pretty, even on a mobile phone. You can swipe the tutorial left and
right for example.

You can see our joint efforts so far for Outcome v2 at
https://ned14.github.io/outcome/. You can thank Andrzej for the tutorial
written so far, it's all him.

Niall

--
ned Productions Limited Consulting
http://www.nedproductions.biz/ http://ie.linkedin.com/in/nialldouglas/


_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Asciidoc, an alternative for documentation

Boost - Dev mailing list
AMDG

On 10/06/2017 03:38 PM, Niall Douglas via Boost wrote:

>
>>> * Does asciidoc allow to show code snips marked in an external source
>>> file? For example, to show example code snips in Quickbook using
>>> [import <file-name>] and then [abc], where //[abc ... //] are used as
>>> markers in file-name.
>>
>> This is the QuickBook feature I would miss. I've used that heavily to
>> ensure that the code embedded in the documentation is code that
>> actually builds and runs, without having to remember to (re-)paste
>> updates into the document source.
>
> I too have been playing with radically different methods of generating
> documentation for Outcome v2, seeing as people panned the v1 Outcome
> documentation.
>
> This is bleeding edge stuff i.e. it currently segfaults a lot, but it is
> getting there. It uses Hugo to compile the Markdown source files into
> HTML via a Travis per-commit job. Standardese may - once Jonathan fixes
> the bugs - generate the reference API docs in Markdown from doxygen
> marked up C++ source files using libclang.
>
> If we can get it working, it'll be a whole new age of "easy" for writing
> docs for complex C++ codebases,

  Er, I've always considered the hard part of documentation
to be the organization and content rather than specific tools.

> and moreover one which finally can parse
> the worst possible C++ metaprogramming without blinking because anything
> clang can parse can be documented.

  Just because the parser can handle it, doesn't mean that
it's a good idea.  For example, in documentation, I always
hide complex SFINAE, and instead provide an English description
of the conditions.  In general, I find the more complex the
metaprogramming is, the more tweaking is required to turn
the doxygen output into something sane.  This is rarely because
doxygen can't parse the code, but is rather because the raw
definitions in the source are not very human-friendly.

> You literally run just two build
> tools, both easily executed from Travis, and push the changes to
> gh-pages on Github. Changing documentation is as easy as modifying the
> Markdown source or the doxygen format comment section in the relevant
> header, git commit and git push. Hugo generates the syntax highlighting,
> the wiki linking, the search index and everything else. Oh, and it looks
> pretty, even on a mobile phone. You can swipe the tutorial left and
> right for example.
>
> You can see our joint efforts so far for Outcome v2 at
> https://ned14.github.io/outcome/. You can thank Andrzej for the tutorial
> written so far, it's all him.
>

In Christ,
Steven Watanabe


_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Asciidoc, an alternative for documentation

Boost - Dev mailing list
On 07.10.2017 05:12, Steven Watanabe via Boost wrote:

> AMDG
>
> On 10/06/2017 03:38 PM, Niall Douglas via Boost wrote:
>> and moreover one which finally can parse
>> the worst possible C++ metaprogramming without blinking because anything
>> clang can parse can be documented.
>    Just because the parser can handle it, doesn't mean that
> it's a good idea.  For example, in documentation, I always
> hide complex SFINAE, and instead provide an English description
> of the conditions.  In general, I find the more complex the
> metaprogramming is, the more tweaking is required to turn
> the doxygen output into something sane.  This is rarely because
> doxygen can't parse the code, but is rather because the raw
> definitions in the source are not very human-friendly.

standardese is designed to handle such things.

For example, if you have:

```
template <typename T, typename = std::enable_if_t<…>>
void foo(const T& obj);
```

You can write the following documentation comment:

```
/// \notes Thie function does not participate in overload resolution
unless T is …
/// \param 1
/// \exlude
```

And standardese will completely hide the SFINAE part away.

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Asciidoc, an alternative for documentation

Boost - Dev mailing list
In reply to this post by Boost - Dev mailing list
On 10/6/17 8:12 PM, Steven Watanabe via Boost wrote:

>> If we can get it working, it'll be a whole new age of "easy" for writing
>> docs for complex C++ codebases,
>
>    Er, I've always considered the hard part of documentation
> to be the organization and content rather than specific tools.

So, so, so, true.  I huge problem these days is that the attractive
presentation of documentation gives the impression that documentation is
well done.  It's very, very misleading.  It's a plague.  I have a lot to
say about this very phenomenon in my recent presentation at cppcon 2017.
Hopefully the video will be available shortly.  I wasn't totally happy
with my presentation, testimony to how difficult is to capture the
problem and address it.

There have been a few recent boost library submissions which have
suffered in this area to the extent I believe they may have turned a
possible acceptance to a rejection.  In one case I believe that a
previously rejected library was accepted and a large part of that change
of assessment was due to much improved documentation.

So, contrary to what one might think, I do believe we are making some
progress in this area.

>> and moreover one which finally can parse
>> the worst possible C++ metaprogramming without blinking because anything
>> clang can parse can be documented.
>
>    Just because the parser can handle it, doesn't mean that
> it's a good idea.  For example, in documentation, I always
> hide complex SFINAE, and instead provide an English description
> of the conditions.  In general, I find the more complex the
> metaprogramming is, the more tweaking is required to turn
> the doxygen output into something sane.  This is rarely because
> doxygen can't parse the code, but is rather because the raw
> definitions in the source are not very human-friendly.

The question of how to document/explain certain C++ constructs such as
template parameters, concepts and meta functions is an interesting one.
Tools like Doxygen and others don't address this.  It's not obvious and
not described by any "tutorials" on documentation.  Actually, there
isn't even a concensus.  In a recent review, I complained that
requirements on template parameters weren't document.  The library
submitter countered that it wasn't necessary because the code contained
static_asserts to enforce (otherwise undocumented) requirements.  Even
the C++ standard calls for this - yet it's often skipped.  SGI documents
describe documentation standards in detail - but this is almost ignored.

>>
>> You can see our joint efforts so far for Outcome v2 at
>> https://ned14.github.io/outcome/. You can thank Andrzej for the tutorial
>> written so far, it's all him.

Andrezej is a great writer who understands all this.  I know this
personally from

a) reading his blog
b) going back and forth with him on the documentation structure of the
safe numerics library.  Though this effort is better than most, there
have been a lot of problems with this and he is one of the few that
understands this stuff.  We share a common view as to what documentation
should be.  So his criticisms are on point and almost always correct.
He is also very meticulous which helps me a lot.

To summarize:

a) Our (boost and C++ generally) problem is not rooted in the tools,
though the tools don't help much.

b) There is growing recognition that it's a serious problem both in
boost and C++ generally.

c) In reviews, we're more critical of documentation than we used to be
and suggestions to improve it are more constructive.

So things are slowly getting better. I'm optimistic about the future.

Robert Ramey




_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Asciidoc, an alternative for documentation

Boost - Dev mailing list


On 07/10/2017 17:25, Robert Ramey via Boost wrote:

> On 10/6/17 8:12 PM, Steven Watanabe via Boost wrote:
>
>>> If we can get it working, it'll be a whole new age of "easy" for
>>> writing
>>> docs for complex C++ codebases,
>>
>>    Er, I've always considered the hard part of documentation
>> to be the organization and content rather than specific tools.
>
> So, so, so, true.  I huge problem these days is that the attractive
> presentation of documentation gives the impression that documentation
> is well done.  It's very, very misleading.  It's a plague.

Indeed, but there's another issue here I would like to raise:

* How do you know when a library is well designed?

The answer for me at least in part is:

* Can I, starting with a blank sheet of paper, easily explain what this
does?

I've lost track of the number of times I've redesigned something because
it failed that test.

The problem I see then, is that tools that extract documentation direct
from code have the effect of disengaging the authors brain from the task
of explaining what their code actually does.  Well it does for me anyway ;)

I've also come to the conclusion that standardese does not make good
documentation - despite having authored more than my fair share.

And now I'll get back to lurking again.... John.



---
This email has been checked for viruses by AVG.
http://www.avg.com


_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Asciidoc, an alternative for documentation

Boost - Dev mailing list
On Sat, Oct 7, 2017 at 10:25 AM, John Maddock via Boost
<[hidden email]> wrote:
> ...standardese does not make good documentation

That's correct. However, it DOES make a good reference.

For example, here's a reference (generated with a tool):
<http://www.boost.org/doc/libs/develop/libs/beast/doc/html/beast/quickref.html>
<http://www.boost.org/doc/libs/develop/libs/beast/doc/html/beast/ref/boost__beast__http__async_write/overload1.html>

And here's "documentation" (i.e. the exposition written by hand)

<http://www.boost.org/doc/libs/develop/libs/beast/doc/html/beast/using_http/message_stream_operations.html>

Lets use the tools for where they do the most good rather than making
blanket statements about not using them.

Thanks

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Asciidoc, an alternative for documentation

Boost - Dev mailing list
In reply to this post by Boost - Dev mailing list
On 10/7/2017 12:25 PM, Robert Ramey via Boost wrote:

> On 10/6/17 8:12 PM, Steven Watanabe via Boost wrote:
>
>>> If we can get it working, it'll be a whole new age of "easy" for writing
>>> docs for complex C++ codebases,
>>
>>    Er, I've always considered the hard part of documentation
>> to be the organization and content rather than specific tools.
>
> So, so, so, true.  I huge problem these days is that the attractive
> presentation of documentation gives the impression that documentation is
> well done.  It's very, very misleading.  It's a plague.  I have a lot to
> say about this very phenomenon in my recent presentation at cppcon 2017.
> Hopefully the video will be available shortly.  I wasn't totally happy
> with my presentation, testimony to how difficult is to capture the
> problem and address it.
>
> There have been a few recent boost library submissions which have
> suffered in this area to the extent I believe they may have turned a
> possible acceptance to a rejection.  In one case I believe that a
> previously rejected library was accepted and a large part of that change
> of assessment was due to much improved documentation.
>
> So, contrary to what one might think, I do believe we are making some
> progress in this area.

The major problem with library docs is always that programmers become
too lazy to explain what the various things are that library actually
does and what the constructs are to achieve each of those various
things. Instead, for too many programmers, library documentation is 99%
examples and a reference, the latter being nothing more than a listing
of constructs which can be used, with no explanation of when or why one
might want to use them. That's it for an awful lot of developers ! And
as long as programmers in general consider that as adequate
documentation, library developers will continue to follow that model.
Even when you point out to programmers that such documentation is
inadequate for end-users who actually want to use your library, the
usual response is just bafflement that the end-user doesn't "get it".

I understand that programmers do not want to write documentation, but
want to create really nifty and useful libraries and programming
constructs. I understand that many developers are not native English
speakers and find it quite onerous to write documentation in a secondary
language which they can almost never know as well as their own primary
language. I sympathize with both these problems. But unless docs can
explain to end-users what is useful about a library and how that
usefulness translates to the constructs of that library, library
documentation will not be adequate for a great many intelligent
programmers.

I feel like an old dinosaur writing this. The current age of computer
programming expects so little of documentation that I am probably
already obsolete in my documentation needs. But I hope programmers will
try to understand that the most brilliant library is useless if it
cannot be understood or, conversely, if understanding it takes such an
inordinate amount of end-user's time that he just gives up in trying to
use the library.

I think very little of this has to do with tools per se. I am certainly
for the best tools which anyone finds easy and adequate to use. Rather
this problem has to deal with the approach to documentation as a means
to explain what one offers as library functionality.

>
>>> and moreover one which finally can parse
>>> the worst possible C++ metaprogramming without blinking because anything
>>> clang can parse can be documented.
>>
>>    Just because the parser can handle it, doesn't mean that
>> it's a good idea.  For example, in documentation, I always
>> hide complex SFINAE, and instead provide an English description
>> of the conditions.  In general, I find the more complex the
>> metaprogramming is, the more tweaking is required to turn
>> the doxygen output into something sane.  This is rarely because
>> doxygen can't parse the code, but is rather because the raw
>> definitions in the source are not very human-friendly.
>
> The question of how to document/explain certain C++ constructs such as
> template parameters, concepts and meta functions is an interesting one.
> Tools like Doxygen and others don't address this.  It's not obvious and
> not described by any "tutorials" on documentation.  Actually, there
> isn't even a concensus.  In a recent review, I complained that
> requirements on template parameters weren't document.  The library
> submitter countered that it wasn't necessary because the code contained
> static_asserts to enforce (otherwise undocumented) requirements.  Even
> the C++ standard calls for this - yet it's often skipped.  SGI documents
> describe documentation standards in detail - but this is almost ignored.
>
>>>
>>> You can see our joint efforts so far for Outcome v2 at
>>> https://ned14.github.io/outcome/. You can thank Andrzej for the tutorial
>>> written so far, it's all him.
>
> Andrezej is a great writer who understands all this.  I know this
> personally from
>
> a) reading his blog
> b) going back and forth with him on the documentation structure of the
> safe numerics library.  Though this effort is better than most, there
> have been a lot of problems with this and he is one of the few that
> understands this stuff.  We share a common view as to what documentation
> should be.  So his criticisms are on point and almost always correct. He
> is also very meticulous which helps me a lot.
>
> To summarize:
>
> a) Our (boost and C++ generally) problem is not rooted in the tools,
> though the tools don't help much.
>
> b) There is growing recognition that it's a serious problem both in
> boost and C++ generally.
>
> c) In reviews, we're more critical of documentation than we used to be
> and suggestions to improve it are more constructive.
>
> So things are slowly getting better. I'm optimistic about the future.
>
> Robert Ramey


_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Asciidoc, an alternative for documentation

Boost - Dev mailing list
In reply to this post by Boost - Dev mailing list
> In a recent review, I complained that
> requirements on template parameters weren't document.  The library
> submitter countered that it wasn't necessary because the code contained
> static_asserts to enforce (otherwise undocumented) requirements.  Even
> the C++ standard calls for this - yet it's often skipped.

Luckily for you Concepts (and C++ 20? I am unsure) brings the "requires"
keyword, thus ensuring that every single template can simultaneously
document and constrain its types in straight C++.

No documentation tool, including Standardese, is currently able to
extract requires clauses yet though. But it'll come eventually.

(And yes, Outcome v2 is 100% Concepts TS ready, and thus all templates
and their parameters specify their requirements)

> Andrezej is a great writer who understands all this.  I know this
> personally from

He's doing a great job with Outcome. So much so I intend to leave him at
it. I'll write my usual word soup for the advanced tutorial sections
such as how to use the ADL customisation points etc. But I am not
capable of better in the time I have available to me.

> a) Our (boost and C++ generally) problem is not rooted in the tools,
> though the tools don't help much.

Boost tooling is painful. I have to think with Boost tooling. I don't
want to have to think, I want to get on with it.

doxygen suffers badly from this too as soon as you push it a bit. You
end up writing lots of simplifying constructs for it with #ifdef.
Painful. Standardese doesn't suffer from that part at least.

Niall

--
ned Productions Limited Consulting
http://www.nedproductions.biz/ http://ie.linkedin.com/in/nialldouglas/


_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Asciidoc, an alternative for documentation

Boost - Dev mailing list
In reply to this post by Boost - Dev mailing list
> * How do you know when a library is well designed?
>
> The answer for me at least in part is:
>
> * Can I, starting with a blank sheet of paper, easily explain what this
> does?
>
> I've lost track of the number of times I've redesigned something because
> it failed that test.

There is currently a mini-repeat of the Outcome v1 review happening on
std-proposals. Many of the same points being made there by the
uninitiated expert as was made here back in May. Same progressions of
understanding. Same arrival at the same conclusions. It's encouraging.
But also slightly surprising, the simpler the concept, the harder it
seems to become for people to grok it in a strange way.

But it also contradicts what you just said. You can very easily explain
a library e.g. ASIO. It's a networking library. Done. But does that have
much relation to its good or bad design? Same goes for Expected|Outcome.
It lets functions return a T|E, like std::variant. But is the Expected
or is the Outcome design good or bad? What are the merits and
disadvantages of each design decision? How do you weigh them?

> The problem I see then, is that tools that extract documentation direct
> from code have the effect of disengaging the authors brain from the task
> of explaining what their code actually does.  Well it does for me anyway ;)
>
> I've also come to the conclusion that standardese does not make good
> documentation - despite having authored more than my fair share.

Standardese as in the word soup they put in the C++ standard is not
documentation. I tried my hand at writing some of it for the operator
try proposal, and immediately got nit picked on lots of bits in it. I'm
no language lawyer. I care about *themes*, shapes, forms, fit like any
library not compiler developer. Nit picky detail for me is just
punctuation, to be added or removed as needed so long as it doesn't
break ABI.

Which is why I'm not on WG21! Nor would be much use there I should think.

But Standardese the tool for generating reference API docs is a large
improvement on doxygen, and once it matures quite a bit ought to be very
useful for Boost type C++. Be appalled, after all, at how useless the
doxygen "extract all" dump of Outcome v2 is:
https://ned14.github.io/outcome/doxygen/namespaceoutcome__v2__xxx.html.
Far too much implementation detail, it's useless.

But Standardese the tool once we get it working ought to chop that very
nicely down into the "just right" balance between detail and
need-to-know-this. And being pretty in presentation and disability
friendly doesn't hurt.

Niall

--
ned Productions Limited Consulting
http://www.nedproductions.biz/ http://ie.linkedin.com/in/nialldouglas/


_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Asciidoc, an alternative for documentation

Boost - Dev mailing list
In reply to this post by Boost - Dev mailing list
On 10/7/17 10:25 AM, John Maddock via Boost wrote:

>
> Indeed, but there's another issue here I would like to raise:
>
> * How do you know when a library is well designed?
>
> The answer for me at least in part is:
>
> * Can I, starting with a blank sheet of paper, easily explain what this
> does?
>
> I've lost track of the number of times I've redesigned something because
> it failed that test.

WOW - Great minds think alike!  I'm hoping you can find time to skip
through the video of my presentation a CPPCon 2017 - if only so you can
honestly endorse it.   The short versions is

a) normal process code, test then write documentation.  Doesn't work.

b) recommended process:  Write documentation in parallel with design and
coding.
step 1: write one sentence description of what the library is meant to do.
Step 2: make a simple illustrative example of how the library is to be
used. If required make more examples.
step 3: make the library to make the examples work.
Step 4: fix library and examples so they make sense.
Step 5: add notes. step 6: Fill in reference documentation using
standard format - e.g. SGI format.

c) This what I do and I think its extremely helpful.  The main benefit
is that I find design mistakes sooner so I have to do less rework.
Second benefit is that final product is better and has list "added in"
quirky features.

> The problem I see then, is that tools that extract documentation direct
> from code have the effect of disengaging the authors brain from the task
> of explaining what their code actually does.  Well it does for me anyway ;)

100% agree.  I do agree that these tools might be helpful - but only up
to a point.

>
> I've also come to the conclusion that standardese does not make good
> documentation - despite having authored more than my fair share.

LOL - at least you've atoned for your sins.  But really the standards
have a different problem.  Not so much as to help users, but more
intended to help implementors.  I would argue it's whole different problem.

> And now I'll get back to lurking again.... John.

Right.  What do we have to do to get you to make a conference appearance
- if only to prove that you're an actual person rather than some robot,
high school student, prison inmate with a life sentence or some thing else.

Robert Ramey


_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Asciidoc, an alternative for documentation

Boost - Dev mailing list
In reply to this post by Boost - Dev mailing list
On 10/7/17 2:55 PM, Niall Douglas via Boost wrote:

>> a) Our (boost and C++ generally) problem is not rooted in the tools,
>> though the tools don't help much.
>
> Boost tooling is painful. I have to think with Boost tooling. I don't
> want to have to think, I want to get on with it.

Ahhh, this explains a lot.  Don't do it this way.
> doxygen suffers badly from this too as soon as you push it a bit. You
> end up writing lots of simplifying constructs for it with #ifdef.
> Painful. Standardese doesn't suffer from that part at least.

I'm always down on DOxygen.  But that's a little unfair.  If DOxygen is
restricted to filling in the reference section it's OK.  It can be made
work in this role.  The probem comes when one starts to thing that this
product IS the documentation.  It's only part of - the easy part.  It's
a paraphrase and formating of the header files.  Of some value granted.
But I'm afraid that many developers stop there and consider themselves
done.  Or they try and "extend" DOxygen through macros to handle things
for which it's not a good fit.

My approach described above is really helpful.  It makes the
documentation much less tedious to write.  and shorter too.  And it
makes your code simpler and shorter also.

Try it and get back to me.

Robert Ramey


_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
12