Recommendations for documentation authors

newer
Google Summar of Code 2024 -...

older
[website][string_ref] Broken link...

Andrzej Krzemienski

2 Jan 2024 2 Jan '24

8:55 a.m.

Hi Boost Developers, And a happy New Year (at least for those who recognize the Gregorian calendar). While I consider improving the documentation quality of some Boost libraries, I wonder if there are any tool or workflow recommendations for the library authors regarding the documentation. I know we do not force any specific tool or format, so I am only asking about recommendations. I note that page https://www.preview.boost.org has at https://www.preview.boost.org/doc/contributor-guide/docs/documentation-guide... the following:

...

The format for documentation on the new website is AsciiDoc Syntax Quick Reference https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/.

Should I treat it as a recommendation to use AsciiDoc? I note that quite a few new libraries choose it. I also see the advantage: you need no special tool for it: a simple web browser knows how to format it. But I found the documentation of libraries that use adoc to be uncomfortable to read. I do not know if this is the tool itself or maybe the correlation between the choice of the tool and the devotion to documentation quality, or maybe something else. It is quite subjective. The older libraries' documentation (using BoostDoc) seemed more friendly and easier to navigate. But to write and maintain such documentation is a challenge. Last year something broke in my pipeline (QuickDoc, xstlproc) and to this day I am not able to determine what it is. So, relying on too complex flows, which become obsolete over time, also doesn't seem like a good idea. I wonder if any of you have similar thoughts, and if you can recommend something for writing good quality and user friendly documentation. Regards, &rzej;

Show replies by date

Andrey Semashev

2 Jan 2 Jan

11:52 a.m.

On 1/2/24 11:55, Andrzej Krzemienski via Boost wrote:

...

Hi Boost Developers, And a happy New Year (at least for those who recognize the Gregorian calendar).

While I consider improving the documentation quality of some Boost libraries, I wonder if there are any tool or workflow recommendations for the library authors regarding the documentation. I know we do not force any specific tool or format, so I am only asking about recommendations.

I note that page https://www.preview.boost.org has at https://www.preview.boost.org/doc/contributor-guide/docs/documentation-guide... the following:

...
The format for documentation on the new website is AsciiDoc Syntax Quick Reference https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/.

Should I treat it as a recommendation to use AsciiDoc? I note that quite a few new libraries choose it. I also see the advantage: you need no special tool for it: a simple web browser knows how to format it.

But I found the documentation of libraries that use adoc to be uncomfortable to read. I do not know if this is the tool itself or maybe the correlation between the choice of the tool and the devotion to documentation quality, or maybe something else. It is quite subjective. The older libraries' documentation (using BoostDoc) seemed more friendly and easier to navigate. But to write and maintain such documentation is a challenge. Last year something broke in my pipeline (QuickDoc, xstlproc) and to this day I am not able to determine what it is. So, relying on too complex flows, which become obsolete over time, also doesn't seem like a good idea.

I wonder if any of you have similar thoughts, and if you can recommend something for writing good quality and user friendly documentation.

To me, QuickBook is the most powerful tool for writing documentation, so I'm not going to recommend anything new. As the changelog says, the latest version supports direct HTML output, but I haven't tried it. I imagine, it should work for simple docs without BoostBook/DocBook specific features. I think, it would be very useful to continue improving QuickBook, in particular to support additional output formats, maybe even AsciiDoc. We have lots of documentation written in it, and new libraries use it as well. Perhaps, if you post some details about your problems with QuickBook, someone will be able to help.

John Maddock

1:08 p.m.

...

...
But I found the documentation of libraries that use adoc to be uncomfortable to read. I do not know if this is the tool itself or maybe the correlation between the choice of the tool and the devotion to documentation quality, or maybe something else. It is quite subjective. The older libraries' documentation (using BoostDoc) seemed more friendly and easier to navigate. But to write and maintain such documentation is a challenge. Last year something broke in my pipeline (QuickDoc, xstlproc) and to this day I am not able to determine what it is. So, relying on too complex flows, which become obsolete over time, also doesn't seem like a good idea.

I wonder if any of you have similar thoughts, and if you can recommend something for writing good quality and user friendly documentation. To me, QuickBook is the most powerful tool for writing documentation, so I'm not going to recommend anything new. As the changelog says, the latest version supports direct HTML output, but I haven't tried it. I imagine, it should work for simple docs without BoostBook/DocBook specific features.

I think, it would be very useful to continue improving QuickBook, in particular to support additional output formats, maybe even AsciiDoc. We have lots of documentation written in it, and new libraries use it as well.

Perhaps, if you post some details about your problems with QuickBook, someone will be able to help.

+1.

Andrzej Krzemienski

1:23 p.m.

wt., 2 sty 2024 o 12:52 Andrey Semashev via Boost napisał(a):

...

On 1/2/24 11:55, Andrzej Krzemienski via Boost wrote:

...
Hi Boost Developers, And a happy New Year (at least for those who recognize the Gregorian calendar).

While I consider improving the documentation quality of some Boost libraries, I wonder if there are any tool or workflow recommendations for the library authors regarding the documentation. I know we do not force any specific tool or format, so I am only asking about recommendations.

I note that page https://www.preview.boost.org has at

https://www.preview.boost.org/doc/contributor-guide/docs/documentation-guide...

...
the following:

...
The format for documentation on the new website is AsciiDoc Syntax Quick Reference https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/.

Should I treat it as a recommendation to use AsciiDoc? I note that quite a few new libraries choose it. I also see the advantage: you need no special tool for it: a simple web browser knows how to format it.

But I found the documentation of libraries that use adoc to be uncomfortable to read. I do not know if this is the tool itself or maybe the correlation between the choice of the tool and the devotion to documentation quality, or maybe something else. It is quite subjective. The older libraries' documentation (using BoostDoc) seemed more friendly and easier to navigate. But to write and maintain such documentation is a challenge. Last year something broke in my pipeline (QuickDoc, xstlproc) and to this day I am not able to determine what it is. So, relying on too complex flows, which become obsolete over time, also doesn't seem like a good idea.

I wonder if any of you have similar thoughts, and if you can recommend something for writing good quality and user friendly documentation.

To me, QuickBook is the most powerful tool for writing documentation, so I'm not going to recommend anything new. As the changelog says, the latest version supports direct HTML output, but I haven't tried it. I imagine, it should work for simple docs without BoostBook/DocBook specific features.

I think, it would be very useful to continue improving QuickBook, in particular to support additional output formats, maybe even AsciiDoc. We have lots of documentation written in it, and new libraries use it as well.

Perhaps, if you post some details about your problems with QuickBook, someone will be able to help.

Thank you for the response. So, let me give you my story, and maybe you -- or anyone else in this list -- can give me some advice. As probably most of us, I have only limited time to devote to Boost maintenance. I have one library in charge that I inherited from Fernando: Boost.Optional. I inherited a working toolchain for producing documentation and I try not to touch it: only modify the content. There is a Jamfile that to the initiated probably tells everything: https://github.com/boostorg/optional/blob/develop/doc/Jamfile.v2 I do not know what it does exactly. I know it uses BoostBook and QuickBook. It uses xsltproc indirectly, I guess. Can I use QuickBook without a BoostBook for the Boost documentation? Is someone doing it already? I tried to have a look at QuickBook docs ( https://www.boost.org/doc/libs/1_84_0/doc/html/quickbook.html) and I cannot figure out if it is a format or a tool that transforms one format into another. I guess it is the latter, but what does it output? How many tools do I have to learn to write documentation for a Boost Library? Of course, I could learn all of it. If I had unlimited time. But I only have like a couple of hours in a week or sometimes month. I barely have time to do the maintenance of the source code and the tests. This is my experience, but I suppose something similar is faced by anyone who considers proposing their libraries into Boost. I enclose the output from my running the `b2` command in folder doc. I would greatly appreciate it if anyone can help me fix this. But even if this is fixed, I would still want to know why this chain of QuickBook -> BoostBook is needed. Regards, &rzej;

...

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

Andrey Semashev

4:22 p.m.

On 1/2/24 16:23, Andrzej Krzemienski wrote:

...

So, let me give you my story, and maybe you -- or anyone else in this list -- can give me some advice. As probably most of us, I have only limited time to devote to Boost maintenance. I have one library in charge that I inherited from Fernando: Boost.Optional. I inherited a working toolchain for producing documentation and I try not to touch it: only modify the content. There is a Jamfile that to the initiated probably tells everything: https://github.com/boostorg/optional/blob/develop/doc/Jamfile.v2 https://github.com/boostorg/optional/blob/develop/doc/Jamfile.v2 I do not know what it does exactly. I know it uses BoostBook and QuickBook. It uses xsltproc indirectly, I guess.

Can I use QuickBook without a BoostBook for the Boost documentation? Is someone doing it already?

My admittedly superfluous understanding is, the pipeline used in the Jamfile is QuickBook -> BoostBook -> DocBook -> HTML. Optionally, the final destination may be PDF instead of HTML, but I don't think we regularly build it these days, so it is of little interest. The xml rule in the Jamfile invokes QuickBook and produces BoostBook on output. The boostbook rule does the rest. For some libraries, you can also see a doxygen rule, which, as you may have guessed, invokes Doxygen and produces BoostBook output, which is then included into QuickBook output via `xinclude` directive and gets into the final output as part of the BoostBook content. Doing so allows to reference Doxygen-generated content from QuickBook content. I haven't seen any library using a direct QuickBook -> HTML pipeline, although the QuickBook executable has the command line switches for it. I haven't looked whether b2 has support for it either.

...

I tried to have a look at QuickBook docs (https://www.boost.org/doc/libs/1_84_0/doc/html/quickbook.html https://www.boost.org/doc/libs/1_84_0/doc/html/quickbook.html) and I cannot figure out if it is a format or a tool that transforms one format into another. I guess it is the latter, but what does it output?

It is both the markup format and the tool that converts content in that format to another format. Primarily, BoostBook. BoostBook is a Boost's extension of the standard DocBook format. Both are XML, and therefore are mainly processed with XSL stylesheets. The stylesheets to convert BoostBook to DocBook are in tools/boostbook. Stylesheets and tools for processing DocBook are installed externally (e.g. on Debian-based systems, via the docbook-xml package).

...

How many tools do I have to learn to write documentation for a Boost Library?

If you mean documentation using QuickBook then at least two: b2 and QuickBook. You need b2 because it is used to build official Boost documentation. And you need QuickBook because, well, you write in it. You don't need to know BoostBook, although for advanced usage it may be useful. For example, you may want to insert BoostBook fragments into QuickBook if you want to use some feature not supported by QuickBook. You may want to look into its stylesheets though, if you want to know what individual xml parameters do in the Jamfile (look for xsl:param tags in tools/boostbook/xsl). Most parameters have a description.

...

I enclose the output from my running the `b2` command in folder doc. I would greatly appreciate it if anyone can help me fix this.

...

From your output it looks like the problem is during conversion from BoostBook to DocBook. Which means either BoostBook content is broken, or

Boost.Optional docs build successfully for me, albeit with a few warnings. I have created a PR to fox the warnings. I am using up-to-date everything from Boost develop. there is a problem with the BoostBook stylesheets. Check if your tools/boostbook is pristine and up-to-date, and rebuild tools/quickbook from scratch using `b2 release link=static`. Then try building the docs again, from scratch.

...

But even if this is fixed, I would still want to know why this chain of QuickBook -> BoostBook is needed.

This follows from my description above. BoostBook is a means to integrate Doxygen output into the docs and a way to produce different kinds of output (HTML or PDF). While the latter is of little demand lately, Doxygen integration is a very much needed feature.

John Maddock

3 Jan 3 Jan

9:42 a.m.

...

So, let me give you my story, and maybe you -- or anyone else in this list -- can give me some advice. As probably most of us, I have only limited time to devote to Boost maintenance. I have one library in charge that I inherited from Fernando: Boost.Optional. I inherited a working toolchain for producing documentation and I try not to touch it: only modify the content. There is a Jamfile that to the initiated probably tells everything: https://github.com/boostorg/optional/blob/develop/doc/Jamfile.v2 I do not know what it does exactly. I know it uses BoostBook and QuickBook. It uses xsltproc indirectly, I guess. Correct, think of quickbook as an "easy" way to write Docbook XML, everything else is just a means of converting the XML to a human readable output.

Can I use QuickBook without a BoostBook for the Boost documentation? Is someone doing it already? No idea. I tried to have a look at QuickBook docs ( https://www.boost.org/doc/libs/1_84_0/doc/html/quickbook.html) and I cannot figure out if it is a format or a tool that transforms one format into another. I guess it is the latter, but what does it output? Docbook XML.

How many tools do I have to learn to write documentation for a Boost Library?

Only quickbook. I agree that the long toolchain required to transform the XML into something useful is painful to set up. Ironically it was chosen precisely because it was externally maintained.

...

Of course, I could learn all of it. If I had unlimited time. But I only have like a couple of hours in a week or sometimes month. I barely have time to do the maintenance of the source code and the tests.

This is my experience, but I suppose something similar is faced by anyone who considers proposing their libraries into Boost.

I enclose the output from my running the `b2` command in folder doc. I would greatly appreciate it if anyone can help me fix this.

I suspect the information we need isn't showing up in there, and this all works for me locally, I'm using: xsltproc: libxml 20708, libxslt 10126 and libexslt 815 Docbook DTD 4.2 Docbook XSL stylesheets 1.79.1 My hunch is that you "upgraded" the docbook DTD to something other than 4.2 - and that's wrong, it's not something that can ever be upgraded, it's a language specification, and we're fixed in stone at version 4.2. Very occasionally, newer versions of the stylesheets can cause issues, but these are rare, and the stylesheets are well maintained IMO.

...

But even if this is fixed, I would still want to know why this chain of QuickBook -> BoostBook is needed.

The idea was to transform to a common language (Docbook) that multiple external tools could parse and handle the actual formatting in a range of outputs (html, pdf, man, html-help etc). John.

Vinnie Falco

2:48 p.m.

On Wed, Jan 3, 2024 at 1:42 AM John Maddock via Boost wrote:

...

xsltproc: libxml 20708, libxslt 10126 and libexslt 815 Docbook DTD 4.2 Docbook XSL stylesheets 1.79.1

Sam Darwin, our C++ Alliance CTO, can help with integration issues like this. Please visit the #boost channel in the Official C++ Language Slack Workspace (https://cppalliance.org/slack) for immediate assistance. I have asked him to review this thread and reply here if possible.

Andrzej Krzemienski

2 Jan 2 Jan

1:36 p.m.

wt., 2 sty 2024 o 12:52 Andrey Semashev via Boost napisał(a):

...

On 1/2/24 11:55, Andrzej Krzemienski via Boost wrote:

...
Hi Boost Developers, And a happy New Year (at least for those who recognize the Gregorian calendar).

While I consider improving the documentation quality of some Boost libraries, I wonder if there are any tool or workflow recommendations for the library authors regarding the documentation. I know we do not force any specific tool or format, so I am only asking about recommendations.

I note that page https://www.preview.boost.org has at

https://www.preview.boost.org/doc/contributor-guide/docs/documentation-guide...

...
the following:

...
The format for documentation on the new website is AsciiDoc Syntax Quick Reference https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/.

Should I treat it as a recommendation to use AsciiDoc? I note that quite a few new libraries choose it. I also see the advantage: you need no special tool for it: a simple web browser knows how to format it.

But I found the documentation of libraries that use adoc to be uncomfortable to read. I do not know if this is the tool itself or maybe the correlation between the choice of the tool and the devotion to documentation quality, or maybe something else. It is quite subjective. The older libraries' documentation (using BoostDoc) seemed more friendly and easier to navigate. But to write and maintain such documentation is a challenge. Last year something broke in my pipeline (QuickDoc, xstlproc) and to this day I am not able to determine what it is. So, relying on too complex flows, which become obsolete over time, also doesn't seem like a good idea.

I wonder if any of you have similar thoughts, and if you can recommend something for writing good quality and user friendly documentation.

To me, QuickBook is the most powerful tool for writing documentation, so I'm not going to recommend anything new. As the changelog says, the latest version supports direct HTML output, but I haven't tried it. I imagine, it should work for simple docs without BoostBook/DocBook specific features.

I think, it would be very useful to continue improving QuickBook, in particular to support additional output formats, maybe even AsciiDoc. We have lots of documentation written in it, and new libraries use it as well.

Perhaps, if you post some details about your problems with QuickBook, someone will be able to help.

((I am reposting this as the previous reply contained too big an attachment)) Thank you for the response. So, let me give you my story, and maybe you -- or anyone else in this list -- can give me some advice. As probably most of us, I have only limited time to devote to Boost maintenance. I have one library in charge that I inherited from Fernando: Boost.Optional. I inherited a working toolchain for producing documentation and I try not to touch it: only modify the content. There is a Jamfile that to the initiated probably tells everything: https://github.com/boostorg/optional/blob/develop/doc/Jamfile.v2 I do not know what it does exactly. I know it uses BoostBook and QuickBook. It uses xsltproc indirectly, I guess. Can I use QuickBook without a BoostBook for the Boost documentation? Is someone doing it already? I tried to have a look at QuickBook docs ( https://www.boost.org/doc/libs/1_84_0/doc/html/quickbook.html) and I cannot figure out if it is a format or a tool that transforms one format into another. I guess it is the latter, but what does it output? How many tools do I have to learn to write documentation for a Boost Library? Of course, I could learn all of it. If I had unlimited time. But I only have like a couple of hours in a week or sometimes month. I barely have time to do the maintenance of the source code and the tests. This is my experience, but I suppose something similar is faced by anyone who considers proposing their libraries into Boost. Under the following link is the output from my running the `b2` command in the folder `doc`. I would greatly appreciate it if anyone can help me fix this. https://raw.githubusercontent.com/akrzemi1/__sandbox__/master/output.txt But even if this is fixed, I would still want to know why this chain of QuickBook -> BoostBook is needed. Regards, &rzej;

Sam Darwin

3 Jan 3 Jan

3:14 p.m.

...

How many tools do I have to learn to write documentation for a Boost Library? Under the following link is the output from my running the `b2` command in the folder `doc`. I would greatly appreciate it if anyone can help me fix this.

Andrzej, in order to build boost documentation, many packages must be installed locally, at the right version number. The Jamfile needs to point to those locations. If a prerequisite is missing it won't build. Here are scripts to get set up to build docs: https://github.com/boostorg/release-tools/tree/master/build_docs The script installs packages which might conflict with existing installations on your local machine. In that case, run it inside a container or a cloud VM if you prefer.

Andrzej Krzemienski

4:37 p.m.

śr., 3 sty 2024 o 16:14 Sam Darwin via Boost napisał(a):

...

...
How many tools do I have to learn to write documentation for a Boost Library? Under the following link is the output from my running the `b2` command in the folder `doc`. I would greatly appreciate it if anyone can help me fix this.

Andrzej, in order to build boost documentation, many packages must be installed locally, at the right version number. The Jamfile needs to point to those locations. If a prerequisite is missing it won't build.

Here are scripts to get set up to build docs: https://github.com/boostorg/release-tools/tree/master/build_docs

The script installs packages which might conflict with existing installations on your local machine. In that case, run it inside a container or a cloud VM if you prefer.

Thanks a bunch. For now, I have upgraded my Fedora, redownloaded the Boost repo, and lo, my documentation builds! I guess I will never know what that was. Regards, &rzej;

...

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

Robert Ramey

7:55 p.m.

On 1/3/24 8:37 AM, Andrzej Krzemienski via Boost wrote:

...

For now, I have upgraded my Fedora, redownloaded the Boost repo, and lo, my documentation builds! I guess I will never know what that was.

Regards, &rzej;

FWIW - here is the shell script I use to build the HTML documentation for the safe numerics library. https://github.com/boostorg/safe_numerics/blob/develop/doc/boostbook/makehtm... There is a similar one to build PDF documentation. Basically, it transforms the DocBook XML into the specified targets. I don't use quickbook so I didn't need to include this is the script. I'm sure it could easily be added though. I did require download a couple of tools: xstltproc, ?.dtd, etc. But once that was done, things run pretty smoothly with not opaque magic. Keep it simple stupid - that's my motto. Robert Ramey

John Maddock

4 Jan 4 Jan

9:30 a.m.

On 03/01/2024 19:55, Robert Ramey via Boost wrote:

...

On 1/3/24 8:37 AM, Andrzej Krzemienski via Boost wrote:

...
For now, I have upgraded my Fedora, redownloaded the Boost repo, and lo, my documentation builds! I guess I will never know what that was.

Regards, &rzej;

FWIW - here is the shell script I use to build the HTML documentation for the safe numerics library.

https://github.com/boostorg/safe_numerics/blob/develop/doc/boostbook/makehtm...

There is a similar one to build PDF documentation.

Basically, it transforms the DocBook XML into the specified targets. I don't use quickbook so I didn't need to include this is the script. I'm sure it could easily be added though.

I did require download a couple of tools: xstltproc, ?.dtd, etc. But once that was done, things run pretty smoothly with not opaque magic.

Keep it simple stupid - that's my motto.

Good shout: Boost.Math has a Makefile which does he same and includes the quickbook step, plus optional PDF output: https://github.com/boostorg/math/blob/develop/doc/win32_nmake.mak Note that quickbook itself outputs Docbook directly, the BoostBook->Docbook step that Boost.Build puts in there is actually redundant (though mostly harmless). John.

Andrzej Krzemienski

2 Jan 2 Jan

3:13 p.m.

wt., 2 sty 2024 o 12:52 Andrey Semashev via Boost napisał(a):

...

On 1/2/24 11:55, Andrzej Krzemienski via Boost wrote:

...
Hi Boost Developers, And a happy New Year (at least for those who recognize the Gregorian calendar).

While I consider improving the documentation quality of some Boost libraries, I wonder if there are any tool or workflow recommendations for the library authors regarding the documentation. I know we do not force any specific tool or format, so I am only asking about recommendations.

I note that page https://www.preview.boost.org has at

https://www.preview.boost.org/doc/contributor-guide/docs/documentation-guide...

...
the following:

...
The format for documentation on the new website is AsciiDoc Syntax Quick Reference https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/.

Should I treat it as a recommendation to use AsciiDoc? I note that quite a few new libraries choose it. I also see the advantage: you need no special tool for it: a simple web browser knows how to format it.

But I found the documentation of libraries that use adoc to be uncomfortable to read. I do not know if this is the tool itself or maybe the correlation between the choice of the tool and the devotion to documentation quality, or maybe something else. It is quite subjective. The older libraries' documentation (using BoostDoc) seemed more friendly and easier to navigate. But to write and maintain such documentation is a challenge. Last year something broke in my pipeline (QuickDoc, xstlproc) and to this day I am not able to determine what it is. So, relying on too complex flows, which become obsolete over time, also doesn't seem like a good idea.

I wonder if any of you have similar thoughts, and if you can recommend something for writing good quality and user friendly documentation.

To me, QuickBook is the most powerful tool for writing documentation, so I'm not going to recommend anything new. As the changelog says, the latest version supports direct HTML output, but I haven't tried it. I imagine, it should work for simple docs without BoostBook/DocBook specific features.

So, when you are recommending QuickBook, does this also imply BoostBook/DocBook, or are you treating them as separate tools? Regards, &rzej;

...

I think, it would be very useful to continue improving QuickBook, in particular to support additional output formats, maybe even AsciiDoc. We have lots of documentation written in it, and new libraries use it as well.

Perhaps, if you post some details about your problems with QuickBook, someone will be able to help.

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

Andrey Semashev

4:33 p.m.

On 1/2/24 18:13, Andrzej Krzemienski wrote:

...

wt., 2 sty 2024 o 12:52 Andrey Semashev via Boost mailto:boost@lists.boost.org> napisał(a):

To me, QuickBook is the most powerful tool for writing documentation, so I'm not going to recommend anything new. As the changelog says, the latest version supports direct HTML output, but I haven't tried it. I imagine, it should work for simple docs without BoostBook/DocBook specific features.

So, when you are recommending QuickBook, does this also imply BoostBook/DocBook, or are you treating them as separate tools?

QuickBook+Doxygen (which both produce BoostBook) is the combination I'm using and recommending. This combination implies BoostBook usage in background. No, it doesn't mean one has to *learn* BoostBook to be able to use it. In fact, I have never written in BoostBook through all the years I have used this combination, aside from a few escapes in QuickBook templates. Which may no longer be necessary with modern QuickBook. I'll note that there was a time when people wrote docs in raw BoostBook, which is probably why QuickBook appeared in the first place. Those times are long passed now. BoostBook *is* a separate tool, though, as you have to configure it in the Jamfile. Most of the time the configuration can be copy-pasted from one of the many libraries in Boost and then tweaked to your liking.

Peter Dimov

8:26 p.m.

Andrey Semashev wrote:

...

I'll note that there was a time when people wrote docs in raw BoostBook, which is probably why QuickBook appeared in the first place. Those times are long passed now.

If I remember correctly, Quickbook was originally a tool that took .qbk markup and produced HTML, similar to Markdown/Asciidoc (which didn't exist.) It was later retargeted to output BoostBook in order for all Boost documentation to be integrated into the same "book" and in order for that "book" to be printable as PDF. This "book" survives here: https://www.boost.org/doc/libs/1_84_0/doc/html/libraries.html The idea of having an "integrated book" doesn't seem to have caught on, however, as most libraries prefer having its own "standalone" documentation that isn't part of the above.

Robert Ramey

8:16 p.m.

...

So, when you are recommending QuickBook, does this also imply BoostBook/DocBook, or are you treating them as separate tools?

Regards, &rzej;

I here's my story with boost documentation tools. I've described my views on documentation content elsewhere: https://www.youtube.com/watch?v=YxmdCxX9dMk I always liked the xml approach of separating document content from document rendering. This permits one to create the content one time and render it according to one's desire at the time. Thus one can produce HTML, PDF, (probably AsciiDoc) and who knows what else. One could also create an xmlsltproc file which would automatically generate a global table of contents for one or all boost libraries - though this has never been done. It also permitted the creating of custom "vocabularies" which would specify more meta data about the content. Doug Gregor created all this in BoostBook but it hasn't been exploited much if any. There remained a few problems though. Editing XML is/was not a user friendly operation. Eric Niebler addressed this by writing QuickBook which produced XML from a simpler text format. This was well received by Boost developers and likely saved XML from failure. I didn't like: The tool chain used B2 to transform the XML into html by invoking xsltproc. I found this to be akin to training an ant to train a flea and too hard for me to do and to keep up with. To this day I have difficulties with B2. I addressed this by editing the raw BoostBook with an XML editor: XMLMind. This is a gui editor which I fund easy to use and lets me visualize the final documentation product as I type. It's also friendly about using "templates" for things like template, class, and function reference documentation. I use a simple shell script to invoke xsltproc to generate html and pdf versions of my docs. I didn't like the usage of DOxygen. I've found this tool to be unsuited to writing documentation of code based on requirements (C++ templates) as opposed to code based on classes. My XML editor easily let me use "templates" for the things I need so no need to try to get DOxygen to do what I needed to do or tweak my C++ comments to make DOxgen do what I wanted. Finally, I ship pre-built documents with my libraries. So anyone who can look up any part of the documentation without having to go on line to do so or with having to build (via B2) A local copy. OK it takes a little extra space. But it's worth it so that users can get immediate answers to their question. It's also easy for them to send a steady stream of typos that I continually correct. Robert Ramey

Vinnie Falco

3:59 p.m.

On Tue, Jan 2, 2024 at 12:55 AM Andrzej Krzemienski via Boost < boost@lists.boost.org> wrote:

...

While I consider improving the documentation quality of some Boost libraries, I wonder if there are any tool or workflow recommendations for the library authors regarding the documentation. I know we do not force any specific tool or format, so I am only asking about recommendations.

The C++ Alliance has a long-running goal of improving documentation for C++ in general, and Boost in particular. First I will tell the story of what I did for the Beast documentation ( https://www.boost.org/doc/libs/1_84_0/libs/beast/doc/html/beast/quickref.htm...). If you don't care about that just jump ahead to what we consider "best practices." When I wrote Beast I really enjoyed the style of the reference section in Boost.Asio, so I copied the toolchain. It took almost two months because the toolchain was quite painful. It works like this (apologies if it is not completely accurate as this is a very complicated process) 1. Doxygen is invoked on header files to produce an XML database of symbol information 2. xsltproc is invoked using XSLT scripts to transform the XML into Quickbook 3. quickbook is invoked to transform the Quickbook into Docbook using Boostbook extensions (Boostbook is a set of Docbook templates) 4. docbook is invoked to transform the Docbook (a form of XML) into HTML (or PDF but I never got that working) What is XSLT you ask? Well, it is a declarative programming language which is formatted in XML and it has loops and control structures. Supposedly, it is specifically designed to process hierarchical input documents such as HTML or XML. Here is an example of an XSLT script which is currently used to transform Doxygen's XML output into Quickbook. Keep in mind that this is actual code: https://github.com/boostorg/docca/blob/0ce4e198398dbb52f1de0029f4ed9b7d2bded... "Docca" is a tool I wrote which is based on Christopher's xslt scripts in Boost.Asio but designed to be reused. Currently the following Boost libraries use docca: Boost.Beast, Boost.JSON, Boost.StaticString, and Boost.URL. Some other libraries might also be using it. XSLT was very painful to learn and it is almost impossible to hire people who know it. I did manage to find one person, Evan Lenz, and C++ Alliance contracted him to work on getting our docca scripts to where they are today. This is what I learned: XSLT is effectively a dead language. Quickbook the tool is unmaintained. Some scripts surrounding it broke, and it is a recurring pain point. XML-based documentation tools in general are kind of dead. Note that Rust avoids all these arcane tools. Now here is one datapoint which pretty much speaks for itself: Peter Dimov and René Ferdinand Rivera Morell use Asciidoctor ( https://asciidoctor.org/). I can't stand the default asciidoc templates, but I have to say that this tool is not only well maintained but it is incredibly popular and only becoming moreso. The authors and contributors have an active messaging forum and Discord chat server. It is used across a variety of programming languages. GitHub automatically previews Asciidoc files: https://github.com/boostorg/url/blob/develop/README.adoc The same cannot be said for Quickbook, Boostbook, or Docbook. Not only is Asciidoctor a great markup language and tool but the authors have also built a document management system on top of it called Antora: https://docs.antora.org/antora/latest/ In terms of best practices, I suggest the following: * Use Asciidoc markdown (.adoc files) for documentation * Run asciidoctor to turn .adoc files into HTML * Use Antora if you want to use the best features in your documentation (such as cross-library documentation linking) The only thing left is a Doxygen-equivalent tool to extract javadoc comments from C++ code and turn it into Asciidoc markdown. The C++ Alliance is working on this tool. I started the project, and now Krystian Stasiowski is the principal engineer. Check out the #mrdocs in the Official C++ Language Slack Workspace (https://cppalliance.org/slack/). The website for mrdocs is here (work in progress): https://mrdocs.com/ Here is a work in progress demo of the Boost.URL library reference rendered in asciidoctor with Mr. Docs: https://mrdocs.com/demos/develop/boost-url/multi/adoc-asciidoc/boost/urls.ht... And here is the recent Boost.Scope library documentation rendered using Mr. Docs: https://mrdocs.com/demos/develop/boost-scope/multi/adoc-asciidoc/boost/scope... We use Antora to render the documentation for the new Boost website. This is an Antora site doc: https://www.preview.boost.org/doc/user-guide/index.html Happy to answer questions. Thanks

René Ferdinand Rivera Morell

5:28 p.m.

On Tue, Jan 2, 2024, 12:00 PM Vinnie Falco via Boost wrote:

...

Now here is one datapoint which pretty much speaks for itself:

Peter Dimov and René Ferdinand Rivera Morell use Asciidoctor ( https://asciidoctor.org/).

An additional point.. I was one of maintainers Quickbook, boostbook, and the b2 support for them. And I gave up on them long ago because of the huge difficulties in the tools. I find asciidoctor to be well maintained and very flexible in it's features. All documentation I write now is with asciidoc including: b2, predef, a variety of wg21 papers, and many more. Key features I like: I can write reference docs directly in the cpp source code, I can include images and SVG, I get live render in vscode. René

Joel de Guzman

3 Jan 3 Jan

2:25 p.m.

On 1/3/24 1:28 AM, René Ferdinand Rivera Morell via Boost wrote:

...

On Tue, Jan 2, 2024, 12:00 PM Vinnie Falco via Boost wrote:

...
Now here is one datapoint which pretty much speaks for itself:

Peter Dimov and René Ferdinand Rivera Morell use Asciidoctor ( https://asciidoctor.org/).

An additional point.. I was one of maintainers Quickbook, boostbook, and the b2 support for them. And I gave up on them long ago because of the huge difficulties in the tools.

I find asciidoctor to be well maintained and very flexible in it's features. All documentation I write now is with asciidoc including: b2, predef, a variety of wg21 papers, and many more. Key features I like: I can write reference docs directly in the cpp source code, I can include images and SVG, I get live render in vscode.

I am the original author of Quickbook. I too have difficulties with the B2, Quickbook, Docbook toolchain and at one point, I just gave up. Now, I too have moved on, and in my newer libraries, I am now also using Asciidoc and Antora. It's far from perfect, and I do miss some of the features of Quickbook such as macros and extracting documentation from cpp source with callouts via [import source.cpp] (*). But as Rene said, Asciidoc is well maintained. (* aside * René, I did not know you can write reference docs directly in the cpp source in Asciidoc. How do you do that?) Here's an example of one my latest libraries: https://cycfi.github.io/q/q/v1.0_beta/reference/synth.html Interestingly, I learned about Asciidoc here, while lurking every once in a while. Quickbook was last maintained by Daniel James up to around 2018. After that, it seems no one picked it up anymore. Sometimes I wonder about modernizing it, but I don't think I want to end up maintaining tools anymore. What's funny is that in the Introduction, I had this quote: “Why program by hand in five days what you can spend five years of your life automating?” -- Terrence Parr, author ANTLR/PCCTS Now I say, five years is an understatement. But life moves on, I suppose. Regards, -- Joel de Guzman

René Ferdinand Rivera Morell

4 Jan 4 Jan

11:46 a.m.

On Wed, Jan 3, 2024 at 10:25 AM Joel de Guzman via Boost wrote:

...

(* aside * René, I did not know you can write reference docs directly in the cpp source in Asciidoc. How do you do that?)

You use the region tagged inclusion https://docs.asciidoctor.org/asciidoc/latest/directives/include-tagged-regio.... It works similarly to the Quickbook snippets (which I used heavily and extended and easily transitioned for asciidoctor). Some examples: * B2: https://github.com/bfgroup/b2/blob/main/src/engine/mod_jam_errors.h, rendered as https://www.bfgroup.xyz/b2/manual/release/index.html#b2.reference.modules.er.... * Predef: https://github.com/boostorg/predef/blob/develop/include/boost/predef/compile..., rendered as https://www.boost.org/doc/libs/1_84_0/libs/predef/doc/index.html#_boost_comp... * Lyra: https://github.com/bfgroup/Lyra/blob/develop/include/lyra/opt.hpp, rendered as https://www.bfgroup.xyz/Lyra/lyra.html#lyra_opt And a non-reference, but still code inclusion example.. https://github.com/bfgroup/Lyra/blob/develop/examples/doc_groups.cpp rendered as https://www.bfgroup.xyz/Lyra/lyra.html#_argument_groups. That mixes both including the doc and source code itself from the cpp file with callouts in the code. And obviously the code is tested to work in B2. So I know the examples are not accidentally broken.

Joel de Guzman

3:02 p.m.

On 1/4/24 7:46 PM, René Ferdinand Rivera Morell wrote:

...

On Wed, Jan 3, 2024 at 10:25 AM Joel de Guzman via Boost wrote:

...
(* aside * René, I did not know you can write reference docs directly in the cpp source in Asciidoc. How do you do that?) You use the region tagged inclusion https://docs.asciidoctor.org/asciidoc/latest/directives/include-tagged-regio.... It works similarly to the Quickbook snippets (which I used heavily and extended and easily transitioned for asciidoctor). Some examples:

* B2: https://github.com/bfgroup/b2/blob/main/src/engine/mod_jam_errors.h, rendered as https://www.bfgroup.xyz/b2/manual/release/index.html#b2.reference.modules.er.... * Predef: https://github.com/boostorg/predef/blob/develop/include/boost/predef/compile..., rendered as https://www.boost.org/doc/libs/1_84_0/libs/predef/doc/index.html#_boost_comp... * Lyra: https://github.com/bfgroup/Lyra/blob/develop/include/lyra/opt.hpp, rendered as https://www.bfgroup.xyz/Lyra/lyra.html#lyra_opt

And a non-reference, but still code inclusion example.. https://github.com/bfgroup/Lyra/blob/develop/examples/doc_groups.cpp rendered as https://www.bfgroup.xyz/Lyra/lyra.html#_argument_groups. That mixes both including the doc and source code itself from the cpp file with callouts in the code. And obviously the code is tested to work in B2. So I know the examples are not accidentally broken.

Sweet! Just what I need. Thanks! Cheers, -- Joel de Guzman

Andrzej Krzemienski

3 Jan 3 Jan

8:01 a.m.

wt., 2 sty 2024 o 17:00 Vinnie Falco napisał(a):

...

On Tue, Jan 2, 2024 at 12:55 AM Andrzej Krzemienski via Boost < boost@lists.boost.org> wrote:

...
While I consider improving the documentation quality of some Boost libraries, I wonder if there are any tool or workflow recommendations for the library authors regarding the documentation. I know we do not force any specific tool or format, so I am only asking about recommendations.

[snip] Now here is one datapoint which pretty much speaks for itself:

...

Peter Dimov and René Ferdinand Rivera Morell use Asciidoctor ( https://asciidoctor.org/).

I can't stand the default asciidoc templates, but I have to say that this tool is not only well maintained but it is incredibly popular and only becoming moreso. The authors and contributors have an active messaging forum and Discord chat server. It is used across a variety of programming languages. GitHub automatically previews Asciidoc files:

https://github.com/boostorg/url/blob/develop/README.adoc

The same cannot be said for Quickbook, Boostbook, or Docbook.

Not only is Asciidoctor a great markup language and tool but the authors have also built a document management system on top of it called Antora:

https://docs.antora.org/antora/latest/

In terms of best practices, I suggest the following:

* Use Asciidoc markdown (.adoc files) for documentation * Run asciidoctor to turn .adoc files into HTML * Use Antora if you want to use the best features in your documentation (such as cross-library documentation linking)

The only thing left is a Doxygen-equivalent tool to extract javadoc comments from C++ code and turn it into Asciidoc markdown. The C++ Alliance is working on this tool. I started the project, and now Krystian Stasiowski is the principal engineer. Check out the #mrdocs in the Official C++ Language Slack Workspace (https://cppalliance.org/slack/). The website for mrdocs is here (work in progress):

https://mrdocs.com/

So at least conceptually, QuickBook->BoostBook flow is doing the same thing as Aciidoc. I also guess that, at least conceptually, the Asciidoc can be made to render as clear and aesthetic output as the QuickBook->BoostBook flow. But for now, it is not true. Do there exist other ready-to-use templates for asciidoctor that would return output suitable for software documentation? I am not satisfied with the present effect of Boost Libraries that choose to use AsciiDoctor for documentation. There may be different causes. Here is a work in progress demo of the Boost.URL library reference rendered

...

in asciidoctor with Mr. Docs:

https://mrdocs.com/demos/develop/boost-url/multi/adoc-asciidoc/boost/urls.ht...

I understand that it is work in progress as for now. I am not satisfied with the present result. Take `pct_encoded_rule_t` for instance. It is listed as "type", but it is actually an alias template whose *role* is to be a *meta-function*. Users need to know about it. This classification into namespaces/types/functions/enums/variables is insufficient for C++. For instance we use classes as *tags* (like std::in_place_t) and this is something different than using classes for maintaining an invariant. There are those cases from Boost.Beast when class X implements function X::f(), as required by the concept, but it does so via derivation. But we want to keep the fact of deriving as an implementation detail not exposed in the documentation. I remember complaining about this to the author, and got a reply "I acknowledge that this is an inconvenience but I am confined to the tool that I am using". I do not know how much additional markup you have to invent to achieve a satisfactory state.

...

And here is the recent Boost.Scope library documentation rendered using Mr. Docs:

https://mrdocs.com/demos/develop/boost-scope/multi/adoc-asciidoc/boost/scope...

While I appreciate the amount of work that went into it, I must say I am not satisfied with the result. Sometimes it boils down to how cautious the author is about putting their annotations, but because the annotations are in the code, the author doesn't have the picture of how they will appear in the context of the documentation. We end up with the situation as in https://mrdocs.com/demos/develop/boost-scope/multi/adoc-asciidoc/boost/scope... Where I need to click on type `result_type` only to learn on a separate page that it is `bool`. wt., 2 sty 2024 o 21:16 Robert Ramey via Boost napisał(a):

...

I here's my story with boost documentation tools. I've described my views on documentation content elsewhere:

https://www.youtube.com/watch?v=YxmdCxX9dMk

I always liked the xml approach of separating document content from document rendering. This permits one to create the content one time and render it according to one's desire at the time. Thus one can produce HTML, PDF, (probably AsciiDoc) and who knows what else. One could also create an xmlsltproc file which would automatically generate a global table of contents for one or all boost libraries - though this has never been done. It also permitted the creating of custom "vocabularies" which would specify more meta data about the content. Doug Gregor created all this in BoostBook but it hasn't been exploited much if any.

The idea to separate contents from the rendering is a sound one. I guess the idea failed in the implementation. For instance, I try to follow your (Robert's) advice to start the documentation with a one-minute introduction that gives the touch and feel of the library. This is impossible with BoostBook, because it generates the Table Of Contents before any content, so the first thing the new user sees is a big table of contents, and they are not aware that if they scrolled down three screens they would get the information they need instantly. wt., 2 sty 2024 o 21:26 Peter Dimov via Boost napisał(a):

...

Andrey Semashev wrote:

...
I'll note that there was a time when people wrote docs in raw BoostBook, which is probably why QuickBook appeared in the first place. Those times are long passed now.

If I remember correctly, Quickbook was originally a tool that took .qbk markup and produced HTML, similar to Markdown/Asciidoc (which didn't exist.)

It was later retargeted to output BoostBook in order for all Boost documentation to be integrated into the same "book" and in order for that "book" to be printable as PDF.

This "book" survives here:

https://www.boost.org/doc/libs/1_84_0/doc/html/libraries.html

The idea of having an "integrated book" doesn't seem to have caught on, however, as most libraries prefer having its own "standalone" documentation that isn't part of the above.

I guess it made sense when Boost was considered a coherent whole. Now, it looks like it is a "federation of unrelated libraries". Also, we seem to have competing libraries (Statechart and MSM). Not sure why someone would want to have one flat book for all of these. I also note that Boost.Optional is not there, even though it uses the QuickBook->BoostBook flow. So I guess it takes something more to qualify for the book. Regards, &rzej;

Vinnie Falco

3:12 p.m.

On Wed, Jan 3, 2024 at 12:01 AM Andrzej Krzemienski wrote:

...

I understand that it is work in progress as for now. I am not satisfied with the present result. Take `pct_encoded_rule_t` for instance. It is listed as "type", but it is actually an alias template whose *role* is to be a *meta-function*. Users need to know about it. This classification into namespaces/types/functions/enums/variables is insufficient for C++. For instance we use classes as *tags* (like std::in_place_t) and this is something different than using classes for maintaining an invariant. There are those cases from Boost.Beast when class X implements function X::f(), as required by the concept, but it does so via derivation. But we want to keep the fact of deriving as an implementation detail not exposed in the documentation.

Yes you are right about all of this, and I too desire better results. However our initial goal is only to replace the use of Doxygen with Mr. Docs in Boost.URL, not to innovate. At least, not yet. Once we have rid ourselves of Doxygen, having better tools to allow us to express things like metafunctions, traits, and concepts is *exactly* the reason why Mr. Docs was started in the first place! Krystian Stasiowski is our principal engineer on the project and he is very knowledgeable with the C++ standard, and he's got big plans for Mr. Docs :) We end up with the situation as in

...

https://mrdocs.com/demos/develop/boost-scope/multi/adoc-asciidoc/boost/scope... Where I need to click on type `result_type` only to learn on a separate page that it is `bool`.

Yes I agree with you. The default set of Mr. Docs templates are designed only to recreate what is currently produced using docca. So as of now Mr. Docs is going to emit reference documentation that looks just like what you will find in Boost.Beast, Boost.JSON, Boost.URL, et. al. The cool thing about Mr. Docs though is that these templates can be customized. I know that many Boost authors prefer a different style where the entire class declaration is repeated at the top of the page, and then individual function signatures (and types) are listed below with corresponding documentation. Like this: https://www.boost.org/doc/libs/1_76_0/libs/system/doc/html/system.html#ref_b... Our future plans for Mr. Docs include the creation of additional template sets to allow for this style of documentation. This is possible without changing any of the C++ code or recompiling Mr. Docs. Of course, if someone wants to start this work today we would be glad to provide assistance. A final note, in terms of rendering metafunctions and that sort of thing we will very likely require concepts as those work quite well. Even if the library does not require C++20, with the use of #ifdef, Mr. Docs can compile the program with C++20 enabled and then the concept declarations will work: #ifdef MRDOCS_USE_CONCEPTS template<typename F> concept has_function_traits = requires { typename function_traits<F>::return_type; typename function_traits<F>::args_type; }; #else template<class F> struct has_function_traits : std::false_type {}; ... #endif C++ Alliance is working with another team in parallel to bring clang/llvm up in terms of features for supporting javadoc comments surrounding concepts and requires clauses. And we are also working on improving the AST representation for these constructs. Thanks

Andrzej Krzemienski

4:40 p.m.

śr., 3 sty 2024 o 16:12 Vinnie Falco napisał(a):

...

On Wed, Jan 3, 2024 at 12:01 AM Andrzej Krzemienski wrote:

...
I understand that it is work in progress as for now. I am not satisfied with the present result. Take `pct_encoded_rule_t` for instance. It is listed as "type", but it is actually an alias template whose *role* is to be a *meta-function*. Users need to know about it. This classification into namespaces/types/functions/enums/variables is insufficient for C++. For instance we use classes as *tags* (like std::in_place_t) and this is something different than using classes for maintaining an invariant. There are those cases from Boost.Beast when class X implements function X::f(), as required by the concept, but it does so via derivation. But we want to keep the fact of deriving as an implementation detail not exposed in the documentation.

Yes you are right about all of this, and I too desire better results. However our initial goal is only to replace the use of Doxygen with Mr. Docs in Boost.URL, not to innovate. At least, not yet. Once we have rid ourselves of Doxygen, having better tools to allow us to express things like metafunctions, traits, and concepts is *exactly* the reason why Mr. Docs was started in the first place!

Krystian Stasiowski is our principal engineer on the project and he is very knowledgeable with the C++ standard, and he's got big plans for Mr. Docs :)

We end up with the situation as in

...
https://mrdocs.com/demos/develop/boost-scope/multi/adoc-asciidoc/boost/scope... Where I need to click on type `result_type` only to learn on a separate page that it is `bool`.

Yes I agree with you. The default set of Mr. Docs templates are designed only to recreate what is currently produced using docca. So as of now Mr. Docs is going to emit reference documentation that looks just like what you will find in Boost.Beast, Boost.JSON, Boost.URL, et. al.

The cool thing about Mr. Docs though is that these templates can be customized. I know that many Boost authors prefer a different style where the entire class declaration is repeated at the top of the page, and then individual function signatures (and types) are listed below with corresponding documentation. Like this:

https://www.boost.org/doc/libs/1_76_0/libs/system/doc/html/system.html#ref_b...

Our future plans for Mr. Docs include the creation of additional template sets to allow for this style of documentation. This is possible without changing any of the C++ code or recompiling Mr. Docs. Of course, if someone wants to start this work today we would be glad to provide assistance.

A final note, in terms of rendering metafunctions and that sort of thing we will very likely require concepts as those work quite well. Even if the library does not require C++20, with the use of #ifdef, Mr. Docs can compile the program with C++20 enabled and then the concept declarations will work:

#ifdef MRDOCS_USE_CONCEPTS template<typename F> concept has_function_traits = requires { typename function_traits<F>::return_type; typename function_traits<F>::args_type; }; #else template<class F> struct has_function_traits : std::false_type {}; ... #endif

C++ Alliance is working with another team in parallel to bring clang/llvm up in terms of features for supporting javadoc comments surrounding concepts and requires clauses. And we are also working on improving the AST representation for these constructs.

Thanks for the update. And about the Asciidoctor templates, does anyone use them to generate Boost documentation with visuals similar to BoostDoc? Regards, &rzej;

311

Age (days ago)

313

Last active (days ago)

List overview

Download

23 comments

9 participants

participants (9)

Andrey Semashev
Andrzej Krzemienski
Joel de Guzman
John Maddock
Peter Dimov
René Ferdinand Rivera Morell
Robert Ramey
Sam Darwin
Vinnie Falco