Re: [boost] Final Getting Started Guide
Roland Schwarz <roland.schwarz@chello.at> writes:
Hallo David,
I already posted the below to the list, but got no response. Possibly it slipped through your attention,
No, it's just down in my priority queue.
since I answered to an old post.
Ah, yes, the link actually is boost_root/doc/html/thread/build.html#thread.build
Thanks...
(without the last ".building")
Roland
David Abrahams wrote:
I refactored the getting started guide into separate documents. Please see
http://www.boost-consulting.com/boost/more/getting_started.html
Library authors have not posted any working URLS of library-specific build instructions, so library names other than Boost.Python all link to the librarys' top-level pages.
For the thread lib this is: boost_root/doc/html/thread/build.html#thread.build.building
This link is available after the docs have been built. No stub available.
While trying to update this piece of the doc I found the following:
1) The getting started guide uses " --toolset= " while the bbv2 manual states " toolset= ". Obviously both versions work. Which one should go into the documentation?
I think most users who don't know more about BBv2 will be less confused by --toolset=. Of course, they may be confused later when they learn more. Tradeoff. I don't find it's a big priority to change, and since I'm busy... :)
2) The Boost.Build ref link from the windows.html getting started points to tools/build/v2. This might be fine when viewed over a web server but opens a directory when viewed from the filesystem. I suggest correcting this link to use the index.html file.
If I find the time.
3) The only place I have found where toolset names are explicitely named is in the getting started guide. I intend to link to /more/getting_started/windows.html#identify-your-toolset. Questions are if this is a stable link
Should be
and how this will work in a pdf scenario?
A "pdf scenario?" I suppose you mean when the Boost docs are generated as PDF? Links to web pages from PDFs just work. That page won't be part of the fraction of Boost docs that are generated as PDF as long as we're going the strict DocBook -> FOP route.
4) I tried to build the getting_started doc on my local machine. But no luck. What do I need beyond using docutils ; in my user-config.jam?
That's all I have. What are your errors? -- Dave Abrahams Boost Consulting www.boost-consulting.com
David Abrahams wrote:
Roland Schwarz <roland.schwarz@chello.at> writes:
Ah, yes, the link actually is boost_root/doc/html/thread/build.html#thread.build
Thanks...
I hope you won't mind, I took the liberty to update the link myself in the RC_1_34_0 branch.
4) I tried to build the getting_started doc on my local machine. But no luck. What do I need beyond using docutils ; in my user-config.jam?
That's all I have. What are your errors?
As I have told you already in another post, the problem is that the docutils.jam explicitely names the rst2html script as rst2html.py . This name is not valid on a debian system. It is the same name with the .py stripped. I was able to get it work by providing a symlink from rst2html.py to rst2html. I suggested, that it would be useful to be able to specify the name of the script in the using docutils statement, just as is possible with the other tools. Regards, Roland
Roland Schwarz <roland.schwarz@chello.at> writes:
David Abrahams wrote:
Roland Schwarz <roland.schwarz@chello.at> writes:
Ah, yes, the link actually is boost_root/doc/html/thread/build.html#thread.build
Thanks...
I hope you won't mind, I took the liberty to update the link myself in the RC_1_34_0 branch.
Please make the fix in the HEAD, too! And update the merged_to_RC_1_34 tag!
4) I tried to build the getting_started doc on my local machine. But no luck. What do I need beyond using docutils ; in my user-config.jam?
That's all I have. What are your errors?
As I have told you already in another post, the problem is that the docutils.jam explicitely names the rst2html script as rst2html.py .
This name is not valid on a debian system. It is the same name with the .py stripped. I was able to get it work by providing a symlink from rst2html.py to rst2html.
I suggested, that it would be useful to be able to specify the name of the script in the using docutils statement, just as is possible with the other tools.
Feel free to make that improvement in CVS. I just did what I needed in order to get going. I'm sure we could do more. -- Dave Abrahams Boost Consulting www.boost-consulting.com
David Abrahams wrote:
Please make the fix in the HEAD, too! And update the merged_to_RC_1_34 tag!
I do understand, that it is a boost policy to change in HEAD and then merge to the release branch. However I am currently in a kind of split-brain situation: 1) We started thread_rewrite, as you might remember, and Anthony and me already were asked to move this to HEAD. 2) We are bugfixing for the RC_1_34_0 branch. 3) I have several options: *) Do bug-fixing in RC_1_34_0, leave HEAD orphaned for the moment, move thread_rewrite to HEAD after release. *) Keeping HEAD in sync with RC_1_34_0 until release and then purge HEAD and move thread_rewrite to HEAD. *) Purge HEAD now, move thread_rewrite to HEAD now, do bug-fixing in RC_1_34_0. I am following the first path for the moment to save time. I would be very interested in your opinion in this matter, and to receive some advice how you think we should proceed. The main problem is, that HEAD and RC_1_34_0 are already very divergent for path 1 and 3, and path 2 only costs time.
I suggested, that it would be useful to be able to specify the name of the script in the using docutils statement, just as is possible with the other tools.
Feel free to make that improvement in CVS. I just did what I needed in order to get going. I'm sure we could do more.
Ok, if I have time, I will look into this. For the moment the link is working for me. Roland
participants (2)
-
David Abrahams -
Roland Schwarz