The Spirit Parser Library

Joel de Guzman wrote:
> Sohail Somani wrote:
>> Error: no ID for constraint linkend:
>> spirit.qi_and_karma.abstracts.parsing_and_generating.the_tokenize_and_phrase_parse___function.
>>
>> Error: no ID for constraint linkend:
>> spirit.lex.lexer_tokenizing.the_generate_static_function.
>> Writing spirit2_HTML.manifest
>>
>> Pretty sure I screwed something up there...
> 
> Nope. That's ok. Please ignore the errors. I'll fix them.

So what do I do after this to get the HTML documentation? I see a
spirit.docbook and spirit.xml file in a subdirectory of bin.v2.

Apologies if this is covered somewhere else.

Thanks!

-- 
Sohail Somani
http://uint32t.blogspot.com

Sohail Somani wrote:
> Joel de Guzman wrote:
>> Sohail Somani wrote:
>>> Error: no ID for constraint linkend:
>>> spirit.qi_and_karma.abstracts.parsing_and_generating.the_tokenize_and_phrase_parse___function.
>>>
>>> Error: no ID for constraint linkend:
>>> spirit.lex.lexer_tokenizing.the_generate_static_function.
>>> Writing spirit2_HTML.manifest
>>>
>>> Pretty sure I screwed something up there...
>> Nope. That's ok. Please ignore the errors. I'll fix them.
> 
> So what do I do after this to get the HTML documentation? I see a
> spirit.docbook and spirit.xml file in a subdirectory of bin.v2.
> 
> Apologies if this is covered somewhere else.

The docs should now be generated in:

     BOOST_ROOT/libs/spirit/doc/html/index.html

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

Joel de Guzman wrote:
> Sohail Somani wrote:
>> Joel de Guzman wrote:
>>> Sohail Somani wrote:
>>>> Error: no ID for constraint linkend:
>>>> spirit.qi_and_karma.abstracts.parsing_and_generating.the_tokenize_and_phrase_parse___function.
>>>>
>>>> Error: no ID for constraint linkend:
>>>> spirit.lex.lexer_tokenizing.the_generate_static_function.
>>>> Writing spirit2_HTML.manifest
>>>>
>>>> Pretty sure I screwed something up there...
>>> Nope. That's ok. Please ignore the errors. I'll fix them.
>> So what do I do after this to get the HTML documentation? I see a
>> spirit.docbook and spirit.xml file in a subdirectory of bin.v2.
>>
>> Apologies if this is covered somewhere else.
> 
> The docs should now be generated in:
> 
>      BOOST_ROOT/libs/spirit/doc/html/index.html
> 
> Regards,

Ok, thanks. Sorry for the repeated messages, thunderbird insisted there
were no new messages in spirit.devel.

-- 
Sohail Somani
http://uint32t.blogspot.com

Joel de Guzman wrote:
> Sohail Somani wrote:
>> Joel de Guzman wrote:
>>> Sohail Somani wrote:
>>>> Error: no ID for constraint linkend:
>>>> spirit.qi_and_karma.abstracts.parsing_and_generating.the_tokenize_and_phrase_parse___function.
>>>>
>>>> Error: no ID for constraint linkend:
>>>> spirit.lex.lexer_tokenizing.the_generate_static_function.
>>>> Writing spirit2_HTML.manifest
>>>>
>>>> Pretty sure I screwed something up there...
>>> Nope. That's ok. Please ignore the errors. I'll fix them.
>> So what do I do after this to get the HTML documentation? I see a
>> spirit.docbook and spirit.xml file in a subdirectory of bin.v2.
>>
>> Apologies if this is covered somewhere else.
> 
> The docs should now be generated in:
> 
>      BOOST_ROOT/libs/spirit/doc/html/index.html
> 
> Regards,

How do you want us to suggest edits? Through svn.boost.org? I was
thinking of having a single ticket for the edits.

-- 
Sohail Somani
http://uint32t.blogspot.com

Sohail Somani wrote:
> Joel de Guzman wrote:
>> Sohail Somani wrote:
>>> Joel de Guzman wrote:
>>>> Sohail Somani wrote:
>>>>> Error: no ID for constraint linkend:
>>>>> spirit.qi_and_karma.abstracts.parsing_and_generating.the_tokenize_and_phrase_parse___function.
>>>>>
>>>>> Error: no ID for constraint linkend:
>>>>> spirit.lex.lexer_tokenizing.the_generate_static_function.
>>>>> Writing spirit2_HTML.manifest
>>>>>
>>>>> Pretty sure I screwed something up there...
>>>> Nope. That's ok. Please ignore the errors. I'll fix them.
>>> So what do I do after this to get the HTML documentation? I see a
>>> spirit.docbook and spirit.xml file in a subdirectory of bin.v2.
>>>
>>> Apologies if this is covered somewhere else.
>> The docs should now be generated in:
>>
>>      BOOST_ROOT/libs/spirit/doc/html/index.html
>>
>> Regards,
> 
> How do you want us to suggest edits? Through svn.boost.org? I was
> thinking of having a single ticket for the edits.

I think that's needless work. Why don't we just edit the QBKs
directly? We can diff the changes anyway. What we can do is flag
each qbk (with a comment perhaps) that it's ready for edit. Then
you guys can do as you will :-)

A good question is how to divide the task between two editors.
Or do we divide it at all? I'll let you and Scott decide.

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

Joel de Guzman wrote:
> Sohail Somani wrote:
>> How do you want us to suggest edits? Through svn.boost.org? I was
>> thinking of having a single ticket for the edits.
> 
> I think that's needless work. Why don't we just edit the QBKs
> directly? We can diff the changes anyway. What we can do is flag
> each qbk (with a comment perhaps) that it's ready for edit. Then
> you guys can do as you will :-)

This is good. We can edit the qbks and then upload them as a patch to a
ticket. Unless you have something else in mind.

> A good question is how to divide the task between two editors.
> Or do we divide it at all? I'll let you and Scott decide.

I don't think we divide it. Scott?

-- 
Sohail Somani
http://uint32t.blogspot.com

Sohail Somani wrote:
> Joel de Guzman wrote:
>> Sohail Somani wrote:
>>> How do you want us to suggest edits? Through svn.boost.org? I was
>>> thinking of having a single ticket for the edits.
>> I think that's needless work. Why don't we just edit the QBKs
>> directly? We can diff the changes anyway. What we can do is flag
>> each qbk (with a comment perhaps) that it's ready for edit. Then
>> you guys can do as you will :-)
> 
> This is good. We can edit the qbks and then upload them as a patch to a
> ticket. Unless you have something else in mind.

Ehm, how about if you just commit directly?

>> A good question is how to divide the task between two editors.
>> Or do we divide it at all? I'll let you and Scott decide.
> 
> I don't think we divide it. Scott?

Same here. It's good to have a consistent editorial style on
the whole. Dividing the docs might give us a disparity in styles.
But I'll let you and Scott decide.

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

Joel de Guzman wrote:
> Hi Y'all,
> 
> So let's get started. First step is to install the QuickBook
> tool-chain. You can get the instructions here:
> 
>     http://www.boost.org/doc/libs/1_39_0/doc/html/quickbook/install.html
> 
> Sorry guys, I know his will be a tough one, but it has to be done.

Oh and BTW, from this point, let's continue the communication over to
the spirit-devel list with the heading prefix: [spirit2-doc]. I'll
do this now.

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

OvermindDL1 wrote:
> On Thu, Jun 18, 2009 at 6:57 PM, Joel de Guzman<joel@...> wrote:
>> It will be the trunk at svn.boost.org, yes. But (ok, got your other
>> reply, hehe), yes, it'll have to be QuickBook.
> 
> Time for me to finally learn the quickbook format then.  :)
> 
> So basically just duplicated an existing reference for something and
> fill it in with something else, shall we submit it to you in email?
> Is there anything we shall do to make sure work is not duplicated?

(BTW, I'm CC'ing the spirit-devel list, let's move the discussion
there).

One reason why I started with the QuickReference is to provide a
map:

     http://tinyurl.com/mcn728 --> Qi
     http://tinyurl.com/mpwqbm --> karma

(BTW, Predefined Primitive Parsers/Generators is wrong. I'll have
to break this table into logical groups).

That's what we need to document. There will be one reference entry
for each of this critters. What we can do is divide and conquer.
If there's 4 of us content writers, we can just divide the N parsers/
generators into 4. Please wait a bit. I'll provide full instructions
on how we shall proceed. In the meantime...

Here's the template I am working on to give you an idea:

[section XXX]

[heading Description]

Description of XXX

[heading Header]

     #include <boost/spirit/xxx.hpp>

[heading Synopsis]

     template <typename T>
     struct XXX;

[heading Template parameters]

[table
     [[Parameter]            [Description]               [Default]]
     [[`T`]                  [What is T]                 []]
]

[heading Model of]

Link to concept

[heading Objects]

Objects provided by the library

[variablelist Notation
     [[`xxx`]     [An XXX]]
]

Semantics of an expression is defined only where it differs from,
or is not defined in _concept-of_XXX_.

[table
   [[Expression] [Semantics]          [Return type] [Complexity]]
   [[`xxx`]      [Semantics of `xxx`] [XXX]         [Constant]]
]

[heading Example]

Real example code. Use Quickbook import mechanism to link to actual
working code snippets here.

[endsect]


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

Joel de Guzman wrote:
> One reason why I started with the QuickReference is to provide a
> map:
> 
>      http://tinyurl.com/mcn728 --> Qi
>      http://tinyurl.com/mpwqbm --> karma

Ooops, sorry:

     http://tinyurl.com/m9rddm --> Qi
     http://tinyurl.com/lx89oc --> Karma

Cheers,
-- 
Joel de Guzman
http://www.boostpro.com
http://spirit.sf.net

Andy Elvey wrote:
> Hi Joel (and all others involved in the docs work) -
> 
> Just checking to ensure that I now have all the required bits to start 
> work.
> I've installed bjam, and also xsltproc, docbook-xsl and docbook-xml (I'm 
> on Ubuntu Linux, btw).  No problems with the installs, all fine.
> 
> The instructions say that "If you're planning on building boost's 
> documentation, you'll also need to install the |doxygen| package as 
> well.".  Does that apply to us when we're building Spirit's docs?  
> (Given that it's part of Boost). Or, is doxygen not needed?
> Thanks in advance -
>  - Andy

No. No need to install Doxygen. We are not using it.

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

Joel de Guzman wrote:
> Andy Elvey wrote:
>   
>> Hi Joel (and all others involved in the docs work) -
>>
>> Just checking to ensure that I now have all the required bits to start 
>> work.
>> I've installed bjam, and also xsltproc, docbook-xsl and docbook-xml (I'm 
>> on Ubuntu Linux, btw).  No problems with the installs, all fine.
>>
>> The instructions say that "If you're planning on building boost's 
>> documentation, you'll also need to install the |doxygen| package as 
>> well.".  Does that apply to us when we're building Spirit's docs?  
>> (Given that it's part of Boost). Or, is doxygen not needed?
>> Thanks in advance -
>>  - Andy
>>     
>
> No. No need to install Doxygen. We are not using it.
>
> Regards,
>   
Ok, that's fine.  Thanks!
- Andy

Hi,

So, we have 2 editors: Sohail Somani and Scott McMurray.
Yea! Thank you Scott and Sohail for volunteering.

We also have 4 content writers. Me, Hartmut, and 2 more
volunteers: Andy Elvey and Overmind. Right now I am gearing
up to get started with the reference docs. It will take me
some time to get the doc-templates ready and to provide some
instructions. I realized I need to get the concept documentation
in first before we can proceed. I'll probably need the weekend
to do that (Hartmut, you might want to sync up with me in what
I am doing with Qi, for Karma).

Anyway, I'd like to take this opportunity to thank the people
who volunteered: Sohail, Scott, Andy, Overmind, EBo (ah there's
one more: Chris Hoeppler who volunteered to proofread).
THANK YOU!

BTW, if there's anyone out here who still want to volunteer,
we're still open for content writers. Let's keep the editors
busy :-P

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

Joel de Guzman wrote:
> Hi,
>
> So, we have 2 editors: Sohail Somani and Scott McMurray.
> Yea! Thank you Scott and Sohail for volunteering.
>
> We also have 4 content writers. Me, Hartmut, and 2 more
> volunteers: Andy Elvey and Overmind. Right now I am gearing
> up to get started with the reference docs. It will take me
> some time to get the doc-templates ready and to provide some
> instructions. I realized I need to get the concept documentation
> in first before we can proceed. I'll probably need the weekend
> to do that (Hartmut, you might want to sync up with me in what
> I am doing with Qi, for Karma).
>
> Anyway, I'd like to take this opportunity to thank the people
> who volunteered: Sohail, Scott, Andy, Overmind, EBo (ah there's
> one more: Chris Hoeppler who volunteered to proofread).
> THANK YOU!
>
> BTW, if there's anyone out here who still want to volunteer,
> we're still open for content writers. Let's keep the editors
> busy :-P
>
> Regards,
>   
You're very welcome... Thank *you* (and all other Spirit devs too) for 
doing such an awesome app!
- Andy

> My last Boost trunk regression test run failed with an error about
> 'lex/lexer_state_switcher_test.cpp' being missing.
> Are the tests supposed to be using lexer_state_switcher.cpp rather than
> lexer_state_switcher_test.cpp ?

Thanks for the heads up. This should be fixed now (rev 53868).

Regards Hartmut