New doc format.

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

New doc format.

Boost - Build mailing list
After asking about documentation tools some months back I ended up doing a full "trial" with asciidoctor to see how it would work out for the new B2 documentation. I realize that others had ideas as to what might be a better tool. But after looking into some others I decided asciidoctor was the least effort to attempt to change to. And that the features, with regards to B2, where sufficiently equivalent with the other top contenders.

You can peruse the result here <https://grafikrobot.github.io/b2doc/>.

There are only some minor items missing in the docs (examples only AFAIK). The process for transferring the docs turned out to involve using quickbook to generate boostbook for the non boostbook parts. And using pandoc to mass translate from boostbook (assuming it was close enough to docbook) to asciidoctor. THen it was a matter of going through all the docs and fixing up any translation errors.

This is just an initial translation.. And will be followed in the future with more automation, style, additions, rewrites, etc changes. Assuming key people are okay with this new set of docs.

--
-- Rene Rivera
-- Grafik - Don't Assume Anything
-- Robot Dreams - http://robot-dreams.net


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

Re: New doc format.

Boost - Build mailing list
AMDG

On 01/14/2018 03:35 PM, Rene Rivera via Boost-build wrote:
> After asking about documentation tools some months back I ended up doing a
> full "trial" with asciidoctor to see how it would work out for the new B2
> documentation. I realize that others had ideas as to what might be a better
> tool. But after looking into some others I decided asciidoctor was the
> least effort to attempt to change to. And that the features, with regards
> to B2, where sufficiently equivalent with the other top contenders.
>
> You can peruse the result here <https://grafikrobot.github.io/b2doc/>.
>

At a quick glance:
- On the front page: s/totorial/tutorial/
- Navigation is really annoying because there is only a single
  global TOC which is restricted to a depth of two levels.
- The index is missing.

> There are only some minor items missing in the docs (examples only AFAIK).
> The process for transferring the docs turned out to involve using quickbook
> to generate boostbook for the non boostbook parts. And using pandoc to mass
> translate from boostbook (assuming it was close enough to docbook)

  Any reason you didn't convert boostbook to docbook?
Just building the docs normally, creates
standalone.docbook as an intermediate step.

> to
> asciidoctor. THen it was a matter of going through all the docs and fixing
> up any translation errors.
>
> This is just an initial translation.. And will be followed in the future
> with more automation, style, additions, rewrites, etc changes. Assuming key
> people are okay with this new set of docs.
>

In Christ,
Steven Watanabe
_______________________________________________
Unsubscribe & other changes: https://lists.boost.org/mailman/listinfo.cgi/boost-build
Reply | Threaded
Open this post in threaded view
|

Re: New doc format.

Boost - Build mailing list
On Sun, Jan 14, 2018 at 5:18 PM, Steven Watanabe via Boost-build <[hidden email]> wrote:
AMDG

On 01/14/2018 03:35 PM, Rene Rivera via Boost-build wrote:
> After asking about documentation tools some months back I ended up doing a
> full "trial" with asciidoctor to see how it would work out for the new B2
> documentation. I realize that others had ideas as to what might be a better
> tool. But after looking into some others I decided asciidoctor was the
> least effort to attempt to change to. And that the features, with regards
> to B2, where sufficiently equivalent with the other top contenders.
>
> You can peruse the result here <https://grafikrobot.github.io/b2doc/>.
>

At a quick glance:
- On the front page: s/totorial/tutorial/

D'oh.. Fixed.
 
- Navigation is really annoying because there is only a single
  global TOC which is restricted to a depth of two levels.

Switched it the side-bar TOC and made it three levels. Makes it a bit better I think. What do you think?
 
- The index is missing.

Yea.. Not sure that's coming back. First, the index entries got lost in translation. Second, although asciidoctor supports marking index entries, it only seems to support them for PDF and docbook output. But.. First, if the docs stay as one html doc an index is not needed terribly as one can just search in the page. Second, the index entries we have in the existing docs are almost entirely useless and rather minimal. So I wouldn't miss having the index. And I would definitely not mind not having to update it :-)
 
> There are only some minor items missing in the docs (examples only AFAIK).
> The process for transferring the docs turned out to involve using quickbook
> to generate boostbook for the non boostbook parts. And using pandoc to mass
> translate from boostbook (assuming it was close enough to docbook)

  Any reason you didn't convert boostbook to docbook? 
Just building the docs normally, creates
standalone.docbook as an intermediate step.

Actually.. I don't remember.. I may have done that :-) It's been a while since I did the initial translation to remember accurately. But I suspect the reason I probably did not was to keep the same set of files (i.e. one-to-one xml-to-adoc).


--
-- Rene Rivera
-- Grafik - Don't Assume Anything
-- Robot Dreams - http://robot-dreams.net


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

Re: New doc format.

Boost - Build mailing list
AMDG

On 01/14/2018 07:21 PM, Rene Rivera wrote:
> On Sun, Jan 14, 2018 at 5:18 PM, Steven Watanabe via Boost-build <
> [hidden email]> wrote:
>
>> On 01/14/2018 03:35 PM, Rene Rivera via Boost-build wrote:
>>>
>>> You can peruse the result here <https://grafikrobot.github.io/b2doc/>.
>>>

- Where is the source?  I've about reached the limit of
  what I have to say about the generated html.
- Quite a lot of links are dead.  (It seems like only links to
  a section are active.)
- The translation is somewhat out-dated vs. develop.
- There's no syntax highlighting for Jam.

>> - Navigation is really annoying because there is only a single
>>   global TOC which is restricted to a depth of two levels.
>>
>
> Switched it the side-bar TOC and made it three levels. Makes it a bit
> better I think. What do you think?
>

  Yeah, that's better, though I have to say that
the section numbers in the TOC for "History" just
look weird, since you have to look closely to see
where the section id ends and the version # starts.

>
>> - The index is missing.
>>
>
> Yea.. Not sure that's coming back. First, the index entries got lost in
> translation. Second, although asciidoctor supports marking index entries,
> it only seems to support them for PDF and docbook output. But.. First, if
> the docs stay as one html doc an index is not needed terribly as one can
> just search in the page. Second, the index entries we have in the existing
> docs are almost entirely useless and rather minimal. So I wouldn't miss
> having the index. And I would definitely not mind not having to update it
> :-)
>

  I don't think it's a great idea to have single
html page.  It's already quite large, and it's
not even close to being complete.  I've been
updating the index for everything I touch.  I've
also been considering passing it though autoindex.

>
>>> There are only some minor items missing in the docs (examples only
>> AFAIK).
>>> The process for transferring the docs turned out to involve using
>> quickbook
>>> to generate boostbook for the non boostbook parts. And using pandoc to
>> mass
>>> translate from boostbook (assuming it was close enough to docbook)
>>
>>   Any reason you didn't convert boostbook to docbook?
>
> Just building the docs normally, creates
>> standalone.docbook as an intermediate step.
>>
>
> Actually.. I don't remember.. I may have done that :-) It's been a while
> since I did the initial translation to remember accurately. But I suspect
> the reason I probably did not was to keep the same set of files (i.e.
> one-to-one xml-to-adoc).
>

  Depending on how much fixing up you had to do, it might
be easier to just split the final output manually.

In Christ,
Steven Watanabe
_______________________________________________
Unsubscribe & other changes: https://lists.boost.org/mailman/listinfo.cgi/boost-build
Reply | Threaded
Open this post in threaded view
|

Re: New doc format.

Boost - Build mailing list
On Tue, Jan 16, 2018 at 10:45 AM, Steven Watanabe via Boost-build <[hidden email]> wrote:
AMDG

On 01/14/2018 07:21 PM, Rene Rivera wrote:
> On Sun, Jan 14, 2018 at 5:18 PM, Steven Watanabe via Boost-build <
> [hidden email]> wrote:
>
>> On 01/14/2018 03:35 PM, Rene Rivera via Boost-build wrote:
>>>
>>> You can peruse the result here <https://grafikrobot.github.io/b2doc/>.
>>>

- Where is the source?  I've about reached the limit of
  what I have to say about the generated html.

It's in the "feature/new-doc-format" branch <https://github.com/boostorg/build/tree/feature/new-doc-format>.
 
- Quite a lot of links are dead.  (It seems like only links to
  a section are active.)

Hmm.. I'll have to figure out how to find and revive missing links.
 
- The translation is somewhat out-dated vs. develop.

I made some catch up changes yesterday. And I have one more to do in that regard (the relevant feature doc addition).
 
- There's no syntax highlighting for Jam.

Was that syntax highlighting manual before? We could certainly work on adding support for syntax coloring for that component. But that would be separate work as it's an off-the-shelf syntax coloring module it uses (which you can configure to use different ones).
 
>> - Navigation is really annoying because there is only a single
>>   global TOC which is restricted to a depth of two levels.
>>
>
> Switched it the side-bar TOC and made it three levels. Makes it a bit
> better I think. What do you think?
>

  Yeah, that's better, though I have to say that
the section numbers in the TOC for "History" just
look weird, since you have to look closely to see
where the section id ends and the version # starts.

Yea, they do.. Perhaps just renaming those heading to "Version X.Y.X" would help. 

> Actually.. I don't remember.. I may have done that :-) It's been a while
> since I did the initial translation to remember accurately. But I suspect
> the reason I probably did not was to keep the same set of files (i.e.
> one-to-one xml-to-adoc).
>

  Depending on how much fixing up you had to do, it might
be easier to just split the final output manually.

I didn't have to do much fixing. Mostly some regex search-replace for some things. Most of the time was reading the doc carefully to ensure everything was there. Although it took a long calendar time.. In reality it only took less than a week of actual work as I had lots of other things in between, including holidays and vacation :-)

--
-- Rene Rivera
-- Grafik - Don't Assume Anything
-- Robot Dreams - http://robot-dreams.net


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

Re: New doc format.

Boost - Build mailing list
AMDG

On 01/16/2018 10:01 AM, Rene Rivera wrote:

> On Tue, Jan 16, 2018 at 10:45 AM, Steven Watanabe via Boost-build <
> [hidden email]> wrote:
>>> - There's no syntax highlighting for Jam.
>>
>
> Was that syntax highlighting manual before? We could certainly work on
> adding support for syntax coloring for that component. But that would be
> separate work as it's an off-the-shelf syntax coloring module it uses
> (which you can configure to use different ones).
>

  boostbook has code for highlighting jam (I wrote it).
I'm assuming that there's some way to plug in our
own highlighter.  It's independent of the rewrite,
but it's something that I want to be implemented before
this goes live.

In Christ,
Steven Watanabe
_______________________________________________
Unsubscribe & other changes: https://lists.boost.org/mailman/listinfo.cgi/boost-build
Reply | Threaded
Open this post in threaded view
|

Re: New doc format.

Boost - Build mailing list
On Tue, Jan 16, 2018 at 12:04 PM, Steven Watanabe via Boost-build <[hidden email]> wrote:
AMDG

On 01/16/2018 10:01 AM, Rene Rivera wrote:
> On Tue, Jan 16, 2018 at 10:45 AM, Steven Watanabe via Boost-build <
> [hidden email]> wrote:
>>> - There's no syntax highlighting for Jam.
>>
>
> Was that syntax highlighting manual before? We could certainly work on
> adding support for syntax coloring for that component. But that would be
> separate work as it's an off-the-shelf syntax coloring module it uses
> (which you can configure to use different ones).
>

  boostbook has code for highlighting jam (I wrote it).
I'm assuming that there's some way to plug in our
own highlighter.

I'll have to check on that. 
 
  It's independent of the rewrite,
but it's something that I want to be implemented before
this goes live.

Sure. I'll go research what options we have on that. In an ideal world we could augment the default one it uses and push that upsream. As that way a bunch of other web contexts would get jam coloring.

--
-- Rene Rivera
-- Grafik - Don't Assume Anything
-- Robot Dreams - http://robot-dreams.net


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

Re: New doc format.

Boost - Build mailing list
In reply to this post by Boost - Build mailing list
AMDG

On 01/14/2018 03:35 PM, Rene Rivera via Boost-build wrote:
>
> This is just an initial translation.. And will be followed in the future
> with more automation, style, additions, rewrites, etc changes. Assuming key
> people are okay with this new set of docs.
>

  One thing that I'm not happy about is the way
the docs are included in the sources.  If we're
going to have the docs in the jam sources, I think
it should be integrated with the --help system,
so it can be viewed from the command line and also
to fit into the codebase better.  I've made some
initial changes to get --help to output adoc (under
the assumption that the doc comments are valid
asciidoc) and it seems feasible.

In Christ,
Steven Watanbe
_______________________________________________
Unsubscribe & other changes: https://lists.boost.org/mailman/listinfo.cgi/boost-build
Reply | Threaded
Open this post in threaded view
|

Re: New doc format.

Boost - Build mailing list
In reply to this post by Boost - Build mailing list
On Tue, Jan 16, 2018 at 1:13 PM, Rene Rivera <[hidden email]> wrote:
On Tue, Jan 16, 2018 at 12:04 PM, Steven Watanabe via Boost-build <[hidden email]> wrote:
AMDG

On 01/16/2018 10:01 AM, Rene Rivera wrote:
> On Tue, Jan 16, 2018 at 10:45 AM, Steven Watanabe via Boost-build <
> [hidden email]> wrote:
>>> - There's no syntax highlighting for Jam.
>>
>
> Was that syntax highlighting manual before? We could certainly work on
> adding support for syntax coloring for that component. But that would be
> separate work as it's an off-the-shelf syntax coloring module it uses
> (which you can configure to use different ones).
>

  boostbook has code for highlighting jam (I wrote it).
I'm assuming that there's some way to plug in our
own highlighter.

I'll have to check on that. 
 
  It's independent of the rewrite,
but it's something that I want to be implemented before
this goes live.

Sure. I'll go research what options we have on that. In an ideal world we could augment the default one it uses and push that upsream. As that way a bunch of other web contexts would get jam coloring.

OK, looked at the coloring.. Did the easiest attempt first. I implemented a jam language coloring for highlight.js. And used that as the coloring for the doc. And I did a partial tagging of the docs with the "[source,jam]" attribute. Please take a look at the updated docs.



--
-- Rene Rivera
-- Grafik - Don't Assume Anything
-- Robot Dreams - http://robot-dreams.net


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

Re: New doc format.

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


On Thu, Jan 18, 2018 at 7:09 PM, Steven Watanabe via Boost-build <[hidden email]> wrote:
AMDG

On 01/14/2018 03:35 PM, Rene Rivera via Boost-build wrote:
>
> This is just an initial translation.. And will be followed in the future
> with more automation, style, additions, rewrites, etc changes. Assuming key
> people are okay with this new set of docs.
>

  One thing that I'm not happy about is the way
the docs are included in the sources. 

Can you explain your unhappiness? As I think having reference documentation in the sources is preferable for a variety of reasons.
 
If we're
going to have the docs in the jam sources, I think
it should be integrated with the --help system,
so it can be viewed from the command line and also
to fit into the codebase better.  I've made some
initial changes to get --help to output adoc (under
the assumption that the doc comments are valid
asciidoc) and it seems feasible.

Okay.. Not sure if it's worth the effort. But I'm not against that.


--
-- Rene Rivera
-- Grafik - Don't Assume Anything
-- Robot Dreams - http://robot-dreams.net


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

Re: New doc format.

Boost - Build mailing list
AMDG

On 01/18/2018 09:57 PM, Rene Rivera wrote:

> On Thu, Jan 18, 2018 at 7:09 PM, Steven Watanabe via Boost-build <
> [hidden email]> wrote:
>
>> On 01/14/2018 03:35 PM, Rene Rivera via Boost-build wrote:
>>>
>>> This is just an initial translation.. And will be followed in the future
>>> with more automation, style, additions, rewrites, etc changes. Assuming
>> key
>>> people are okay with this new set of docs.
>>>
>>
>>   One thing that I'm not happy about is the way
>> the docs are included in the sources.
>
>
> Can you explain your unhappiness? As I think having reference documentation
> in the sources is preferable for a variety of reasons.
>

  I don't think it's a bad thing per se, but I find
the way it was handled to be ugly.  In addition, I really
want the built-in help to work.  In the past, I
went to the trouble of duplicating the documentation
between the jam sources and docbook, which I really hate.

>
>> If we're
>> going to have the docs in the jam sources, I think
>> it should be integrated with the --help system,
>> so it can be viewed from the command line and also
>> to fit into the codebase better.  I've made some
>> initial changes to get --help to output adoc (under
>> the assumption that the doc comments are valid
>> asciidoc) and it seems feasible.
>>
>
> Okay.. Not sure if it's worth the effort. But I'm not against that.
>

  I've just pushed my initial take on this to feature/adoc-help.
It's implemented for asciidoctor.jam and zlib.jam.
What do you think?
(I really wish that asciidoctor had a way to set an
include path.  Copying files into the source directory
just so they can be found is really annoying.)

In Christ,
Steven Watanabe
_______________________________________________
Unsubscribe & other changes: https://lists.boost.org/mailman/listinfo.cgi/boost-build
Reply | Threaded
Open this post in threaded view
|

Re: New doc format.

Boost - Build mailing list
In reply to this post by Boost - Build mailing list
AMDG

On 01/18/2018 09:42 PM, Rene Rivera wrote:

> On Tue, Jan 16, 2018 at 1:13 PM, Rene Rivera <[hidden email]> wrote:
>
>> On Tue, Jan 16, 2018 at 12:04 PM, Steven Watanabe via Boost-build <
>> [hidden email]> wrote:
>>
>>>
>>>   It's independent of the rewrite,
>>> but it's something that I want to be implemented before
>>> this goes live.
>>>
>>
>> Sure. I'll go research what options we have on that. In an ideal world we
>> could augment the default one it uses and push that upsream. As that way a
>> bunch of other web contexts would get jam coloring.
>>
>
> OK, looked at the coloring.. Did the easiest attempt first. I implemented a
> jam language coloring for highlight.js. And used that as the coloring for
> the doc. And I did a partial tagging of the docs with the "[source,jam]"
> attribute. Please take a look at the updated docs.
>
>

It doesn't seem like it quite works:
https://grafikrobot.github.io/b2doc/#bbv2.reference.class.abstract-target

- The highlighting of keywords and rulenames seems
  be interfering with each other somehow.
- The comment/keyword/rule colors seem to be the same.

Note: I can send you my emacs mode, which has the highlighting
mostly correct, if that would help.  I'm also willing to
port one of my existing highlighters myself if you can point
me to the system I need to implement.

Also, I dislike javascript based highlighting on principle.

In Christ,
Steven Watanabe
_______________________________________________
Unsubscribe & other changes: https://lists.boost.org/mailman/listinfo.cgi/boost-build
Reply | Threaded
Open this post in threaded view
|

Re: New doc format.

Boost - Build mailing list
In reply to this post by Boost - Build mailing list
On Fri, Jan 19, 2018 at 4:14 PM, Steven Watanabe via Boost-build <[hidden email]> wrote:
AMDG

On 01/18/2018 09:57 PM, Rene Rivera wrote:
> On Thu, Jan 18, 2018 at 7:09 PM, Steven Watanabe via Boost-build <
> [hidden email]> wrote:
>
>> On 01/14/2018 03:35 PM, Rene Rivera via Boost-build wrote:
>>>
>>> This is just an initial translation.. And will be followed in the future
>>> with more automation, style, additions, rewrites, etc changes. Assuming
>> key
>>> people are okay with this new set of docs.
>>>
>>
>>   One thing that I'm not happy about is the way
>> the docs are included in the sources.
>
>
> Can you explain your unhappiness? As I think having reference documentation
> in the sources is preferable for a variety of reasons.
>

  I don't think it's a bad thing per se, but I find
the way it was handled to be ugly. 

I'm confused on that.. You find the asciidoctor way to be ugly? Something else? 

In addition, I really
want the built-in help to work.

Okay.. But the best you'll be able to do that is to spit back out the plain asciidoc content when one invokes --help. And like I said before.. I don't think the command line is the best place to read documentation. But, hey, if you can make the --help work, great :-) 

  In the past, I
went to the trouble of duplicating the documentation
between the jam sources and docbook, which I really hate.

Right.. I also don't like duplicating this stuff. It's a route to having outdated docs.
 
>> If we're
>> going to have the docs in the jam sources, I think
>> it should be integrated with the --help system,
>> so it can be viewed from the command line and also
>> to fit into the codebase better.  I've made some
>> initial changes to get --help to output adoc (under
>> the assumption that the doc comments are valid
>> asciidoc) and it seems feasible.
>>
>
> Okay.. Not sure if it's worth the effort. But I'm not against that.

  I've just pushed my initial take on this to feature/adoc-help.
It's implemented for asciidoctor.jam and zlib.jam.
What do you think?

I'm trying to understand what you did. You have b2 extract the asciidoc instead of having asciidoctor extract it directly? And you are also taking the "native" b2 doc comments and generating adoc from them? Is there something else?
 
(I really wish that asciidoctor had a way to set an
include path.  Copying files into the source directory
just so they can be found is really annoying.)

There is.. From `asciidoctor --help`:

    -I, --load-path DIRECTORY        add a directory to the $LOAD_PATH
                                     may be specified more than once

Which is already implemented through the usual <include> feature in asciiidoctor.jam.

--
-- Rene Rivera
-- Grafik - Don't Assume Anything
-- Robot Dreams - http://robot-dreams.net


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

Re: New doc format.

Boost - Build mailing list
In reply to this post by Boost - Build mailing list
On Fri, Jan 19, 2018 at 7:12 PM, Steven Watanabe via Boost-build <[hidden email]> wrote:
AMDG

On 01/18/2018 09:42 PM, Rene Rivera wrote:
> On Tue, Jan 16, 2018 at 1:13 PM, Rene Rivera <[hidden email]> wrote:
>
>> On Tue, Jan 16, 2018 at 12:04 PM, Steven Watanabe via Boost-build <
>> [hidden email]> wrote:
>>
>>>
>>>   It's independent of the rewrite,
>>> but it's something that I want to be implemented before
>>> this goes live.
>>>
>>
>> Sure. I'll go research what options we have on that. In an ideal world we
>> could augment the default one it uses and push that upsream. As that way a
>> bunch of other web contexts would get jam coloring.
>>
>
> OK, looked at the coloring.. Did the easiest attempt first. I implemented a
> jam language coloring for highlight.js. And used that as the coloring for
> the doc. And I did a partial tagging of the docs with the "[source,jam]"
> attribute. Please take a look at the updated docs.
>
>

It doesn't seem like it quite works:
https://grafikrobot.github.io/b2doc/#bbv2.reference.class.abstract-target

Hmm.. Not valid Jam code hence the problems. But I can probably make that work anyway. Best I could do with a few hours of work :-)
 
- The highlighting of keywords and rulenames seems
  be interfering with each other somehow.
- The comment/keyword/rule colors seem to be the same.

If you are referring to "rule" being red in the link above.. That's a parsing problem because those rules do have a body. And the parser definition I created assumed legal Jam code. 

Note: I can send you my emacs mode, which has the highlighting
mostly correct, if that would help. 

Wouldn't help since it's been ages since I look at emacs code (and I no longer use it). 
 
I'm also willing to
port one of my existing highlighters myself if you can point
me to the system I need to implement.

All I can do is point you to the docs about highlighters. Specifically which ones it currently supports <http://asciidoctor.org/docs/user-manual/#available-source-highlighters>. I'm assuming to implement your own you'd either have to extend one of those existing ones (like I did). Or write Ruby code to extend asciidoctor.
 
Also, I dislike javascript based highlighting on principle.

I've become a pragmatist for this. I'd rather see something that requires less of my time and is more widely used than worry about which language it's implemented in. And whether it runs at conversion time or in the browser.

--
-- Rene Rivera
-- Grafik - Don't Assume Anything
-- Robot Dreams - http://robot-dreams.net


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

Re: New doc format.

Boost - Build mailing list
In reply to this post by Boost - Build mailing list
AMDG

On 01/19/2018 07:34 PM, Rene Rivera wrote:

> On Fri, Jan 19, 2018 at 4:14 PM, Steven Watanabe via Boost-build <
> [hidden email]> wrote:
>
>> On 01/18/2018 09:57 PM, Rene Rivera wrote:
>>> On Thu, Jan 18, 2018 at 7:09 PM, Steven Watanabe via Boost-build <
>>> [hidden email]> wrote:
>>>
>>>> On 01/14/2018 03:35 PM, Rene Rivera via Boost-build wrote:
>>>>>
>>>>> This is just an initial translation.. And will be followed in the
>> future
>>>>> with more automation, style, additions, rewrites, etc changes. Assuming
>>>> key
>>>>> people are okay with this new set of docs.
>>>>>
>>>>
>>>>   One thing that I'm not happy about is the way
>>>> the docs are included in the sources.
>>>
>>>
>>> Can you explain your unhappiness? As I think having reference
>> documentation
>>> in the sources is preferable for a variety of reasons.
>>>
>>
>>   I don't think it's a bad thing per se, but I find
>> the way it was handled to be ugly.
>
>
> I'm confused on that.. You find the asciidoctor way to be ugly? Something
> else?
>

  Yes.  I don't like tag::doc much, although that's relatively
minor.  What's more important is that it's essentially
folding two independent files which have no understanding
of each other into one.  It's not too bad as long as you just
have a single adoc block at the top, but in general the
linear order of the code is not necessarily the order in
which the documentation needs to appear--fixing that requires
a lot of manual bookkeeping.

> In addition, I really
>> want the built-in help to work.
>
>
> Okay.. But the best you'll be able to do that is to spit back out the plain
> asciidoc content when one invokes --help.

  That's fine.  asciidoc is mostly readable as is.
I just stripped out a few of the obvious things
like ```.  (I actually considered piping it through
asciidoctor -bmanpage -o - - | man -l -, but that
may not be available)

> And like I said before.. I don't
> think the command line is the best place to read documentation. But, hey,
> if you can make the --help work, great :-)
>

  It isn't the best way, but it's often the most
convenient for checking something quickly.

> <snip>
>>   I've just pushed my initial take on this to feature/adoc-help.
>> It's implemented for asciidoctor.jam and zlib.jam.
>> What do you think?
>>
>
> I'm trying to understand what you did. You have b2 extract the asciidoc
> instead of having asciidoctor extract it directly?

  Right.  I'm also adding some structural components
and headings.  I had it use #|! (a la doxygen), although
it still handles plain comments (as long as they're in
exactly the right place).

> And you are also taking
> the "native" b2 doc comments and generating adoc from them?

  Yeah.  They're basically plain text, with a few preformatted
blocks, so just passing them through works.  I switched the
preformatted text to use asciidoc syntax.

> Is there
> something else?
>

- The module and rule docs have a section implicitly
  defined, if you don't put a heading on it explicitly.
  The also get an id equivalent to the jam name, to
  make linking easier.
- class members are structured inside the class rather
  than being read sequentially.

>
>> (I really wish that asciidoctor had a way to set an
>> include path.  Copying files into the source directory
>> just so they can be found is really annoying.)
>>
>
> There is.. From `asciidoctor --help`:
>
>     -I, --load-path DIRECTORY        add a directory to the $LOAD_PATH
>                                      may be specified more than once
>
> Which is already implemented through the usual <include> feature in
> asciiidoctor.jam.
>

  That's the first thing I tried.  It doesn't do what you
think it does.  Here's a slightly different description
from the online docs:

-I, --load-path=DIRECTORY

    Add the specified directory to the load path, so that -r can load
extensions from outside the default Ruby load path

In Christ,
Steven Watanabe
_______________________________________________
Unsubscribe & other changes: https://lists.boost.org/mailman/listinfo.cgi/boost-build
Reply | Threaded
Open this post in threaded view
|

Re: New doc format.

Boost - Build mailing list
In reply to this post by Boost - Build mailing list
On 1/14/18 2:35 PM, Rene Rivera via Boost-build wrote:
> After asking about documentation tools some months back I ended up doing
> a full "trial" with asciidoctor to see how it would work out for the new
> B2 documentation. I realize that others had ideas as to what might be a
> better tool. But after looking into some others I decided asciidoctor
> was the least effort to attempt to change to. And that the features,
> with regards to B2, where sufficiently equivalent with the other top
> contenders.

Is this about new b2 documentation or new format/way of presentation?

I'm very happy with the boost book approach.

I've always been of the the view that B2 documenation content would
benefit from some investment of effort.

Doing both of the above in one shot seems a bad idea to me.

Robert Ramey
_______________________________________________
Unsubscribe & other changes: https://lists.boost.org/mailman/listinfo.cgi/boost-build
Reply | Threaded
Open this post in threaded view
|

Re: New doc format.

Boost - Build mailing list
On Sat, Jan 20, 2018 at 10:37 AM, Robert Ramey via Boost-build <[hidden email]> wrote:
On 1/14/18 2:35 PM, Rene Rivera via Boost-build wrote:
After asking about documentation tools some months back I ended up doing a full "trial" with asciidoctor to see how it would work out for the new B2 documentation. I realize that others had ideas as to what might be a better tool. But after looking into some others I decided asciidoctor was the least effort to attempt to change to. And that the features, with regards to B2, where sufficiently equivalent with the other top contenders.

Is this about new b2 documentation or new format/way of presentation?

Yes. 

I'm very happy with the boost book approach.

What aspect(s) of it are you happy with? 

I've always been of the the view that B2 documenation content would benefit from some investment of effort.

Yes. 

Doing both of the above in one shot seems a bad idea to me.

Not doing both at the same time. First step in this is putting the existing documentation in a format and arrangement that facilitates the editing, creation, and presentation of that documentation to as many audiences as possible. Part of this is also looking forward at a time when B2 will not be primarily advertised as a member of Boost.


--
-- Rene Rivera
-- Grafik - Don't Assume Anything
-- Robot Dreams - http://robot-dreams.net


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

Re: New doc format.

Boost - Build mailing list
On 1/20/18 9:03 AM, Rene Rivera via Boost-build wrote:
>     I'm very happy with the boost book approach.
>
>
> What aspect(s) of it are you happy with?

a) I like the fact that it separates the content from the presentation
so that one can edit the content once and generate as needed renderings
in html, singlepage html, pdf, epub or perhaps something else.

b) I find boost book very easy to edit.  Combined with a) above it lets
me edit boost book without much regard for the final rendering which is
addresses separately.

c) I can tweak the formating of the final rendering via some xmlt.
Granted xml transform is a kludgy system, but I does actually work and
generally their is very little of this work to do.

The fly in the ointment is the actual editing of boost book.  But I have
found this nicely addressed by XMLmind personal edition which can be
downloaded for free
http://www.xmlmind.com/xmleditor/license_xxe_perso.html also see
http://www.xmlmind.com/xmleditor/boostbook.shtml

>     I've always been of the the view that B2 documenation content would
>     benefit from some investment of effort.
>
> Yes.
>
>     Doing both of the above in one shot seems a bad idea to me.
>
> Not doing both at the same time. First step in this is putting the
> existing documentation in a format and arrangement that facilitates the
> editing, creation, and presentation of that documentation to as many
> audiences as possible.

see above

> Part of this is also looking forward at a time
> when B2 will not be primarily advertised as a member of Boost.

Right - Worthy goals.

FWIW - I've never thought that the documentation for B2 was bad - as far
as it goes.  I've felt that:

a) it can be added to and kept more up to date.

b) it's hard to write.  There are two ways of looking at this.

1) Work harder at writing it.
2) Think about why it's hard to write.

I think the correct approach is 2).  When something is really hard to
describe, maybe it's a sign that the thing we're trying to describe
needs to be considered.  Often times it's easier to fix the tool/library
so it makes more sense that to try to describe something that is
actually more complex than it needs to be.  Sources of problems are
implicit behavior, side effects, global settings/variables, non-obvious
inherited behavior, etc.

Robert Ramey
_______________________________________________
Unsubscribe & other changes: https://lists.boost.org/mailman/listinfo.cgi/boost-build
Reply | Threaded
Open this post in threaded view
|

Re: New doc format.

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


On Fri, Jan 19, 2018 at 11:01 PM, Steven Watanabe via Boost-build <[hidden email]> wrote:
AMDG

On 01/19/2018 07:34 PM, Rene Rivera wrote:
> On Fri, Jan 19, 2018 at 4:14 PM, Steven Watanabe via Boost-build <
> [hidden email]> wrote:
>
>> On 01/18/2018 09:57 PM, Rene Rivera wrote:
>>> On Thu, Jan 18, 2018 at 7:09 PM, Steven Watanabe via Boost-build <
>>> [hidden email]> wrote:
>>>
>>>> On 01/14/2018 03:35 PM, Rene Rivera via Boost-build wrote:
>>>>>
>>>>> This is just an initial translation.. And will be followed in the
>> future
>>>>> with more automation, style, additions, rewrites, etc changes. Assuming
>>>> key
>>>>> people are okay with this new set of docs.
>>>>>
>>>>
>>>>   One thing that I'm not happy about is the way
>>>> the docs are included in the sources.
>>>
>>>
>>> Can you explain your unhappiness? As I think having reference
>> documentation
>>> in the sources is preferable for a variety of reasons.
>>>
>>
>>   I don't think it's a bad thing per se, but I find
>> the way it was handled to be ugly.
>
>
> I'm confused on that.. You find the asciidoctor way to be ugly? Something
> else?
>

  Yes.  I don't like tag::doc much, although that's relatively
minor. 

Yea, minor point.  Although I do like the flexibility it provides in being able to mark up the sections in, hopefully, meaningful ways. 
 
What's more important is that it's essentially
folding two independent files which have no understanding
of each other into one.  It's not too bad as long as you just
have a single adoc block at the top, but in general the
linear order of the code is not necessarily the order in
which the documentation needs to appear--fixing that requires
a lot of manual bookkeeping.

That's a really good point. Although I've also found that any ordering I could program it to come out with, say with the --help system, would also be wrong. And hence the best arrangement would only be possible manually, with a bunch of bookkeeping. So I guess the key is to find a way to reduce the bookkeeping to make it possible to arrange the reference documentation in the ideal way.
 
> In addition, I really
>> want the built-in help to work.
>
>
> Okay.. But the best you'll be able to do that is to spit back out the plain
> asciidoc content when one invokes --help.

  That's fine.  asciidoc is mostly readable as is.
I just stripped out a few of the obvious things
like ```.  (I actually considered piping it through
asciidoctor -bmanpage -o - - | man -l -, but that
may not be available)

OK, makes sense. I do like the idea of supporting both. Just didn't think it was worth the effort :-) As I just want better documentation. 

>
>> (I really wish that asciidoctor had a way to set an
>> include path.  Copying files into the source directory
>> just so they can be found is really annoying.)
>>
>
> There is.. From `asciidoctor --help`:
>
>     -I, --load-path DIRECTORY        add a directory to the $LOAD_PATH
>                                      may be specified more than once
>
> Which is already implemented through the usual <include> feature in
> asciiidoctor.jam.
>

  That's the first thing I tried.  It doesn't do what you
think it does.  Here's a slightly different description
from the online docs:

-I, --load-path=DIRECTORY

    Add the specified directory to the load path, so that -r can load
extensions from outside the default Ruby load path

That is unfortunate.. But I'm okay with them getting put in the src dir and added to git also. As they should be stable enough for version control. Regardless.. I also submitted an issue to hopefully get a search path added <https://github.com/asciidoctor/asciidoctor/issues/2540>.

--
-- Rene Rivera
-- Grafik - Don't Assume Anything
-- Robot Dreams - http://robot-dreams.net


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

Re: New doc format.

Boost - Build mailing list
In reply to this post by Boost - Build mailing list
On Sat, Jan 20, 2018 at 11:44 AM, Robert Ramey via Boost-build <[hidden email]> wrote:
On 1/20/18 9:03 AM, Rene Rivera via Boost-build wrote:
    I'm very happy with the boost book approach.


What aspect(s) of it are you happy with?

a) I like the fact that it separates the content from the presentation so that one can edit the content once and generate as needed renderings in html, singlepage html, pdf, epub or perhaps something else.

Right.. We also get that with asciidoctor. 

b) I find boost book very easy to edit.  Combined with a) above it lets me edit boost book without much regard for the final rendering which is addresses separately.

I don't find boost book (aka docbook) easy to edit. 

c) I can tweak the formating of the final rendering via some xmlt. Granted xml transform is a kludgy system, but I does actually work and generally their is very little of this work to do.

The kind of tweaking possible in the final rendering with asciidoc would vary depending on the process and output type. For HTML most likely it would be CSS (or alternative). For docbook output you would be able to use XSLT or whatever XML transforms or styling the eventual target output lets you use. No idea for PDF, and other formats though.
 
The fly in the ointment is the actual editing of boost book.  But I have found this nicely addressed by XMLmind personal edition which can be downloaded for free http://www.xmlmind.com/xmleditor/license_xxe_perso.html also see http://www.xmlmind.com/xmleditor/boostbook.shtml

That is a gigantic fly.. more like a Lucanus maculifemoratus. For Boost Build with it's current 100 individual contributors it would be impractical to ask them to deal with XML or any particular XML editing software. It also has the drawback that we are not able to embed the documentation in source files.

    I've always been of the the view that B2 documenation content would
    benefit from some investment of effort.

Yes.

    Doing both of the above in one shot seems a bad idea to me.

Not doing both at the same time. First step in this is putting the existing documentation in a format and arrangement that facilitates the editing, creation, and presentation of that documentation to as many audiences as possible.

see above

Part of this is also looking forward at a time when B2 will not be primarily advertised as a member of Boost.

Right - Worthy goals.

FWIW - I've never thought that the documentation for B2 was bad - as far as it goes.  I've felt that:

a) it can be added to and kept more up to date.

That particular one is key, as the reason it's not kept more up to date is that it's written in docbook. Which very few of us are comfortable editing. And which deviates from what the source code actually does because it's separate from that code. 

b) it's hard to write.  There are two ways of looking at this.

1) Work harder at writing it.
2) Think about why it's hard to write.

I think the correct approach is 2).  When something is really hard to describe, maybe it's a sign that the thing we're trying to describe needs to be considered.  Often times it's easier to fix the tool/library so it makes more sense that to try to describe something that is actually more complex than it needs to be.  Sources of problems are implicit behavior, side effects, global settings/variables, non-obvious inherited behavior, etc.

Right.. Those need more work. That's a long term goal. And one that will take time and multiple people to make a dent in it.

-- 
-- Rene Rivera
-- Grafik - Don't Assume Anything
-- Robot Dreams - http://robot-dreams.net


_______________________________________________
Unsubscribe & other changes: https://lists.boost.org/mailman/listinfo.cgi/boost-build
12