[IBD] Why don't I see anything about Literate Programming?

[David Abrahams]

   ...unless the code examples in our documentation are tested, they
   will be wrong...

For those willing to use RestructuredText, there is LitRe, in the
tools subdirectory of the Boost tree.  Aleksey and I used that for our
book and Daniel and I used it for the Boost.Parameter docs.
http://lists.boost.org/boost-testing/2005/03/0493.php

--
Dave Abrahams
Boost Consulting
http://www.boost-consulting.com

The Astoria Seminar ==> http://www.astoriaseminar.com


-------------------------------------------------------------------------
This SF.net email is sponsored by DB2 Express
Download DB2 Express C - the FREE version of DB2 express and take
control of your XML. No limits. Just data. Click to get it now.
http://sourceforge.net/powerbar/db2/
_______________________________________________
Boost-docs mailing list
Boost-docs@...
Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs

[John Maddock]

David Abrahams wrote:
>   ...unless the code examples in our documentation are tested, they
>   will be wrong...
>
> For those willing to use RestructuredText, there is LitRe, in the
> tools subdirectory of the Boost tree.  Aleksey and I used that for our
> book and Daniel and I used it for the Boost.Parameter docs.
> http://lists.boost.org/boost-testing/2005/03/0493.php

You can already use quickbook to import your code examples (AKA "reverse
literate programming"), so it is possible to have only one version of an
example, and to have it tested as well as in the docs, albeit not in the way
you invision.

It would still make a great feature though..

John.


-------------------------------------------------------------------------
This SF.net email is sponsored by DB2 Express
Download DB2 Express C - the FREE version of DB2 express and take
control of your XML. No limits. Just data. Click to get it now.
http://sourceforge.net/powerbar/db2/
_______________________________________________
Boost-docs mailing list
Boost-docs@...
Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs

[David Abrahams]

on Wed Jul 11 2007, "John Maddock" <john-AT-johnmaddock.co.uk> wrote:

> David Abrahams wrote:
>>   ...unless the code examples in our documentation are tested, they
>>   will be wrong...
>>
>> For those willing to use RestructuredText, there is LitRe, in the
>> tools subdirectory of the Boost tree.  Aleksey and I used that for our
>> book and Daniel and I used it for the Boost.Parameter docs.
>> http://lists.boost.org/boost-testing/2005/03/0493.php
>
> You can already use quickbook to import your code examples (AKA "reverse
> literate programming"),

I know.

> so it is possible to have only one version of an
> example, and to have it tested as well as in the docs, albeit not in the way
> you invision.
>
> It would still make a great feature though..

Yeah.  Well it doesn't need to be a feature of quickbook... in fact it
probably shouldn't be.  It should be a postprocessing step on the QB
XML output.  We can use QB templates to generate special XML tags that
enclose testing instructions.  Most of the infrastructure of LitRe
could be reused.

--
Dave Abrahams
Boost Consulting
http://www.boost-consulting.com

The Astoria Seminar ==> http://www.astoriaseminar.com


-------------------------------------------------------------------------
This SF.net email is sponsored by DB2 Express
Download DB2 Express C - the FREE version of DB2 express and take
control of your XML. No limits. Just data. Click to get it now.
http://sourceforge.net/powerbar/db2/
_______________________________________________
Boost-docs mailing list
Boost-docs@...
Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs

[Joel de Guzman-2]

David Abrahams wrote:

> on Wed Jul 11 2007, "John Maddock" <john-AT-johnmaddock.co.uk> wrote:
>
>> so it is possible to have only one version of an
>> example, and to have it tested as well as in the docs, albeit not in the way
>> you invision.
>>
>> It would still make a great feature though..
>
> Yeah.  Well it doesn't need to be a feature of quickbook... in fact it
> probably shouldn't be.  It should be a postprocessing step on the QB
> XML output.  We can use QB templates to generate special XML tags that
> enclose testing instructions.  Most of the infrastructure of LitRe
> could be reused.

Rene is working on the standard template stuff for qbk. I'll have
those templates in as soon as Rene's work gets merged into head.
Let's see how it goes.

Regards,
--
Joel de Guzman
http://www.boost-consulting.com
http://spirit.sf.net


-------------------------------------------------------------------------
This SF.net email is sponsored by DB2 Express
Download DB2 Express C - the FREE version of DB2 express and take
control of your XML. No limits. Just data. Click to get it now.
http://sourceforge.net/powerbar/db2/
_______________________________________________
Boost-docs mailing list
Boost-docs@...
Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs

[Rene Rivera-2]

Joel de Guzman wrote:

> David Abrahams wrote:
>> on Wed Jul 11 2007, "John Maddock" <john-AT-johnmaddock.co.uk> wrote:
>>
>>> so it is possible to have only one version of an
>>> example, and to have it tested as well as in the docs, albeit not in the way
>>> you invision.
>>>
>>> It would still make a great feature though..
>> Yeah.  Well it doesn't need to be a feature of quickbook... in fact it
>> probably shouldn't be.  It should be a postprocessing step on the QB
>> XML output.  We can use QB templates to generate special XML tags that
>> enclose testing instructions.  Most of the infrastructure of LitRe
>> could be reused.

Technically it would be possible to run Quickbook with an appropriate
template that generates source code directly skipping the need to use
XML. But this is closer to what Joel mentions than what Dave is
suggesting. The point being that both options are possible, and we
likely want to have both to allow for a range of lightweight to complex
process.

> Rene is working on the standard template stuff for qbk. I'll have
> those templates in as soon as Rene's work gets merged into head.
> Let's see how it goes.

It's getting there, going through all the output actions and turning
them into templates, and testing them is slow work :-( Although the code
that's currently checked in has a good portion implemented (as of
yesterday). I'd say 60% of the output in regular looking docs is
template driven now. I have the hard step of restructuring how lists are
processed next.


--
-- Grafik - Don't Assume Anything
-- Redshift Software, Inc. - http://redshift-software.com
-- rrivera/acm.org - grafik/redshift-software.com
-- 102708583/icq - grafikrobot/aim - grafikrobot/yahoo

-------------------------------------------------------------------------
This SF.net email is sponsored by DB2 Express
Download DB2 Express C - the FREE version of DB2 express and take
control of your XML. No limits. Just data. Click to get it now.
http://sourceforge.net/powerbar/db2/
_______________________________________________
Boost-docs mailing list
Boost-docs@...
Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs

[Matias Capeletto]

On 7/11/07, John Maddock <john@...> wrote:
> David Abrahams wrote:
> >   ...unless the code examples in our documentation are tested, they
> >   will be wrong...

100% agree.

> > For those willing to use RestructuredText, there is LitRe, in the
> > tools subdirectory of the Boost tree.  Aleksey and I used that for our
> > book and Daniel and I used it for the Boost.Parameter docs.
> > http://lists.boost.org/boost-testing/2005/03/0493.php
>
> You can already use quickbook to import your code examples (AKA "reverse
> literate programming"), so it is possible to have only one version of an
> example, and to have it tested as well as in the docs, albeit not in the way
> you invision.
>
> It would still make a great feature though..

Indeed. For small snippets it is somewhat unnatural to keep them
separate from the qbk source.

Best regards
Matias

-------------------------------------------------------------------------
This SF.net email is sponsored by DB2 Express
Download DB2 Express C - the FREE version of DB2 express and take
control of your XML. No limits. Just data. Click to get it now.
http://sourceforge.net/powerbar/db2/
_______________________________________________
Boost-docs mailing list
Boost-docs@...
Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs

[Joel de Guzman-2]

Rene Rivera wrote:

> Joel de Guzman wrote:
>> David Abrahams wrote:
>>> on Wed Jul 11 2007, "John Maddock" <john-AT-johnmaddock.co.uk> wrote:
>>>
>>>> so it is possible to have only one version of an
>>>> example, and to have it tested as well as in the docs, albeit not in the way
>>>> you invision.
>>>>
>>>> It would still make a great feature though..
>>> Yeah.  Well it doesn't need to be a feature of quickbook... in fact it
>>> probably shouldn't be.  It should be a postprocessing step on the QB
>>> XML output.  We can use QB templates to generate special XML tags that
>>> enclose testing instructions.  Most of the infrastructure of LitRe
>>> could be reused.
>
> Technically it would be possible to run Quickbook with an appropriate
> template that generates source code directly skipping the need to use
> XML. But this is closer to what Joel mentions than what Dave is
> suggesting. The point being that both options are possible, and we
> likely want to have both to allow for a range of lightweight to complex
> process.

Yep.

>> Rene is working on the standard template stuff for qbk. I'll have
>> those templates in as soon as Rene's work gets merged into head.
>> Let's see how it goes.
>
> It's getting there, going through all the output actions and turning
> them into templates, and testing them is slow work :-( Although the code
> that's currently checked in has a good portion implemented (as of
> yesterday). I'd say 60% of the output in regular looking docs is

60%! Cool!

> template driven now. I have the hard step of restructuring how lists are
> processed next.

QBk Lists? Hmmm... maybe break it down to some low-level templates
for a) ordered list start/end b) unordered list start/end. c)
list items. Then have qbk generate the templates.

Ditto for tables.

Regards,
--
Joel de Guzman
http://www.boost-consulting.com
http://spirit.sf.net


-------------------------------------------------------------------------
This SF.net email is sponsored by DB2 Express
Download DB2 Express C - the FREE version of DB2 express and take
control of your XML. No limits. Just data. Click to get it now.
http://sourceforge.net/powerbar/db2/
_______________________________________________
Boost-docs mailing list
Boost-docs@...
Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs

[Matias Capeletto]

On 7/11/07, Rene Rivera <grafikrobot@...> wrote:

> Joel de Guzman wrote:
> > Rene is working on the standard template stuff for qbk. I'll have
> > those templates in as soon as Rene's work gets merged into head.
> > Let's see how it goes.
>
> It's getting there, going through all the output actions and turning
> them into templates, and testing them is slow work :-( Although the code
> that's currently checked in has a good portion implemented (as of
> yesterday). I'd say 60% of the output in regular looking docs is
> template driven now. I have the hard step of restructuring how lists are
> processed next.

Wow!
I thought that the project was starting. 60% is a very encouraging percentage.
This are great news :)
Thanks for all this work Rene!

King regards
Matias

-------------------------------------------------------------------------
This SF.net email is sponsored by DB2 Express
Download DB2 Express C - the FREE version of DB2 express and take
control of your XML. No limits. Just data. Click to get it now.
http://sourceforge.net/powerbar/db2/
_______________________________________________
Boost-docs mailing list
Boost-docs@...
Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs

[Rene Rivera-2]

Matias Capeletto wrote:
> Wow!
> I thought that the project was starting. 60% is a very encouraging percentage.

This particular project was on my TODO list for more than a year. And I
finally started it 3 months ago. So it's not going even at slow speed ;-)

> This are great news :)
> Thanks for all this work Rene!

Welcome... even if I'm doing it for mostly selfish reasons :-D


--
-- Grafik - Don't Assume Anything
-- Redshift Software, Inc. - http://redshift-software.com
-- rrivera/acm.org - grafik/redshift-software.com
-- 102708583/icq - grafikrobot/aim - grafikrobot/yahoo

-------------------------------------------------------------------------
This SF.net email is sponsored by DB2 Express
Download DB2 Express C - the FREE version of DB2 express and take
control of your XML. No limits. Just data. Click to get it now.
http://sourceforge.net/powerbar/db2/
_______________________________________________
Boost-docs mailing list
Boost-docs@...
Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs

[Rene Rivera-2]

Joel de Guzman wrote:
> Rene Rivera wrote:
>> It's getting there, going through all the output actions and turning
>> them into templates, and testing them is slow work :-( Although the code
>> that's currently checked in has a good portion implemented (as of
>> yesterday). I'd say 60% of the output in regular looking docs is
>
> 60%! Cool!

Well, note my careful choice of words ;-) It's not 60% of the
directives, or possible output, just of the usual output. Meaning the
usual output is statistically using a smaller percentage of directives
than what is possible.

>> template driven now. I have the hard step of restructuring how lists are
>> processed next.
>
> QBk Lists? Hmmm... maybe break it down to some low-level templates
> for a) ordered list start/end b) unordered list start/end. c)
> list items. Then have qbk generate the templates.

Well, that's the easy part :-) And list items are already generated with
a template. The hard part is redoing the generation so that it doesn't
backtrack on the output to insert sublists into the parent list item.


--
-- Grafik - Don't Assume Anything
-- Redshift Software, Inc. - http://redshift-software.com
-- rrivera/acm.org - grafik/redshift-software.com
-- 102708583/icq - grafikrobot/aim - grafikrobot/yahoo

-------------------------------------------------------------------------
This SF.net email is sponsored by DB2 Express
Download DB2 Express C - the FREE version of DB2 express and take
control of your XML. No limits. Just data. Click to get it now.
http://sourceforge.net/powerbar/db2/
_______________________________________________
Boost-docs mailing list
Boost-docs@...
Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs

[Joel de Guzman-2]

Rene Rivera wrote:

> Joel de Guzman wrote:
>> Rene Rivera wrote:
>>> It's getting there, going through all the output actions and turning
>>> them into templates, and testing them is slow work :-( Although the code
>>> that's currently checked in has a good portion implemented (as of
>>> yesterday). I'd say 60% of the output in regular looking docs is
>> 60%! Cool!
>
> Well, note my careful choice of words ;-) It's not 60% of the
> directives, or possible output, just of the usual output. Meaning the
> usual output is statistically using a smaller percentage of directives
> than what is possible.

Understood. Still, a huge amount! :-)

>>> template driven now. I have the hard step of restructuring how lists are
>>> processed next.
>> QBk Lists? Hmmm... maybe break it down to some low-level templates
>> for a) ordered list start/end b) unordered list start/end. c)
>> list items. Then have qbk generate the templates.
>
> Well, that's the easy part :-) And list items are already generated with
> a template. The hard part is redoing the generation so that it doesn't
> backtrack on the output to insert sublists into the parent list item.

Ah, yeah, tricky.

Regards,
--
Joel de Guzman
http://www.boost-consulting.com
http://spirit.sf.net


-------------------------------------------------------------------------
This SF.net email is sponsored by DB2 Express
Download DB2 Express C - the FREE version of DB2 express and take
control of your XML. No limits. Just data. Click to get it now.
http://sourceforge.net/powerbar/db2/
_______________________________________________
Boost-docs mailing list
Boost-docs@...
Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs

[Matias Capeletto]

On 7/11/07, Rene Rivera <grafikrobot@...> wrote:
> Matias Capeletto wrote:
> > This are great news :)
> > Thanks for all this work Rene!
>
> Welcome... even if I'm doing it for mostly selfish reasons :-D

We are very lucky you are being selfish then... ;)

Please let us now if you need help for anything. It will be great if
you can send mails to the boost-docs list with the count down...
70%
80%...
90%!!!!
1-0-0%

King regards
Mat

-------------------------------------------------------------------------
This SF.net email is sponsored by DB2 Express
Download DB2 Express C - the FREE version of DB2 express and take
control of your XML. No limits. Just data. Click to get it now.
http://sourceforge.net/powerbar/db2/
_______________________________________________
Boost-docs mailing list
Boost-docs@...
Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs