Organization of boost docs

[Matias Capeletto]

Hi,

To summarize yesterday long thread, and to start a formal proposal for
the docs directory layout I have add this to the Improving Boost Docs
project (from now on IBD project) wiki:

http://svn.boost.org/trac/boost/wiki/DocsTranslationsProject#Organizationintherepository

Comments are welcome,

Can we move further discussion to the boost-docs list? I do not feel
right cluttering the main devel list with this stuff.

Best regards
Matias

P.S. The boost-docs list is one of the last in sourceforge. Will it be
possible to start a migration to lists.boost.org. I think now it the
appropriate time.

-------------------------------------------------------------------------
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

[Andrew Sutton]

> Can we move further discussion to the boost-docs list? I do not feel
> right cluttering the main devel list with this stuff.

Sure thing...

> To summarize yesterday long thread, and to start a formal proposal for
> the docs directory layout I have add this to the Improving Boost Docs
> project (from now on IBD project) wiki:
>
> http://svn.boost.org/trac/boost/wiki/ 
> DocsTranslationsProject#Organizationintherepository
>
> Comments are welcome,

Have you given any thought to project-wide documentation resources?  
For example, project-wide icons could go in (and I'm just guessing  
here) boost/doc/images? It would also be nice for project-wide macros  
like assignments for international characters, references to SGI  
concept and class documentation, etc.

For the latter, it would probably be easy to

[include ../../../doc/international.qbk]
[include ../../../doc/sgi.qbk]
etc.

from within the qbk docs or maybe even provide a cmd-line parameter  
to quickbook - kind of like forcing an include file during compilation.

Good work so far.

Andrew Sutton
asutton@...



-------------------------------------------------------------------------
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:
> Comments are welcome,

Some time ago, in Boost CVS HEAD, I moved all the images, css, qbk, xml,
  etc. to root/doc/src/*. The reason is simple, it moves things closer
to being able to generate docs outside of the root/doc/html directory. I
do the same for the docs of other projects (external to Boost). The goal
is to isolate the "sources" from the "output" in the same way C++
sources are isolated from the objects, libs, dlls, exes, etc.


--
-- 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 6/26/07, Andrew Sutton <asutton@...> wrote:
> > Comments are welcome,
>
> Have you given any thought to project-wide documentation resources?
> For example, project-wide icons could go in (and I'm just guessing
> here) boost/doc/images?

Please see this:
http://svn.boost.org/trac/boost/wiki/BoostDocsRepository

What you want is already done there in the folder doc/style.
Checkout the boost docs svn, and look for doc/doc_test. It is an
example of how a library documentation may look. There is no simple
image there, or css.

> It would also be nice for project-wide macros
> like assignments for international characters, references to SGI
> concept and class documentation, etc.
> For the latter, it would probably be easy to
>
> [include ../../../doc/international.qbk]
> [include ../../../doc/sgi.qbk]
> etc.
>
> from within the qbk docs or maybe even provide a cmd-line parameter
> to quickbook - kind of like forcing an include file during compilation.

I think Rene is working in general template libraries.

> Good work so far.

Thanks!
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

[Matias Capeletto]

On 6/26/07, Rene Rivera <grafikrobot@...> wrote:
> Matias Capeletto wrote:
> > Comments are welcome,
>
> Some time ago, in Boost CVS HEAD, I moved all the images, css, qbk, xml,
>   etc. to root/doc/src/*. The reason is simple, it moves things closer
> to being able to generate docs outside of the root/doc/html directory. I
> do the same for the docs of other projects (external to Boost). The goal
> is to isolate the "sources" from the "output" in the same way C++
> sources are isolated from the objects, libs, dlls, exes, etc.

Rene, can you explain this layout a bit more. I am trying to understand it.
There are various things we have to decide:

(1) Where will the .xml and .xsl for each library be?
(2) If a library use quickbook, where do we put the .qbk files?
(3) Where library specific images lives?
(4) Where doc examples (imported from the docs) will be placed?
(5) Where the generated docs are placed? (for html, pdf, man pages, etc)
(6) Where the general style goes? (for html)
(7) Where common resources needed for building the docs lives? (svgs
for pdf generation)

If I have understand your proposal, you want this layout:

* doc/src/    ( Sources needed to generate the doc )

    * doc/src/lib_name/lib_name.xml   ( dockbook docs )
    * doc/src/lib_name/lib_name.xsl    ( stylesheet )
    * doc/src/lib_name/Jamfile.v2        ( generate the docs inside
"doc/html/lib_name" )

    * doc/src/lib_name/*.qbk ( quickbook source )
    * doc/src/lib_name/example/*.cpp ( used code samples )

    * doc/src/pdf/images/*.svg ( I do not know ehere to put this one? )

* doc/html/   ( Html docs for all boost libraries )

    * doc/html/index.html ( entry point )

    * doc/html/lib_name/index.html     ( main entry of the library html docs )
    * doc/html/lib_name/sections.xml ( and others xml files, general
library content )
    * doc/html/lib_name/iamges/*.png ( library specific images )

    * doc/html/style/*.css  ( stylesheets )
    * doc/html/javascript/*.js ( javascript files )

* doc/pdf/   ( pdf docs for all boost libraries )

     * doc/pdf/lib_name/lib_name.pdf

* doc/{other format}/

     * doc/pdf/lib_name/{other format files}

Have I follow you?
I think I like this... I have to think a little more about it.

Best regards
Matias

PS: I do not know if my private email reach you. I copy it here for you:
----------------------------------------------
Hi Rene,

I need a place to store the doc_test html so testers can reliable
check the last version. FTP has become a maintenance nightmare and
Douglas told me to use the website/public_html folder so the files get
updated somewhere in the web when I commit a new version.

Where can I place my folders? Does "website/public_html/boost_docs/"
looks fine for you?

Thanks a lot!
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

[Matias Capeletto]

On 6/26/07, Matias Capeletto <matias.capeletto@...> wrote:

> On 6/26/07, Rene Rivera <grafikrobot@...> wrote:
> > Matias Capeletto wrote:
> If I have understand your proposal, you want this layout:
>
> * doc/src/    ( Sources needed to generate the doc )
>
>     * doc/src/lib_name/lib_name.xml   ( dockbook docs )
>     * doc/src/lib_name/lib_name.xsl    ( stylesheet )
>     * doc/src/lib_name/Jamfile.v2        ( generate the docs inside
> "doc/html/lib_name" )
>
>     * doc/src/lib_name/*.qbk ( quickbook source )
>     * doc/src/lib_name/example/*.cpp ( used code samples )

Having other things (html, pdf, style, etc) as my last mail, I want to
know what are the pros of this layout for sources instead of the
actual one:

* libs/lib_name/doc/

     * doc/lib_name/doc/lib_name.xml   ( dockbook docs )
     * doc/lib_name/doc/lib_name.xsl    ( stylesheet )
     * doc/lib_name/doc/Jamfile.v2        ( generate docs inside
"doc/html/lib_name" )

     * doc/lib_name/doc/*.qbk ( quickbook source )
     * doc/lib_name/example/doc/*.cpp ( or doc/example )

The thing I like about this layout is that everything a library author
maintainer has to modify lives in "libs/lib_name". ( Not counting the
files inside the boost headers directory, because that is a different
business )
I fail to see why the other scheme better separate the sources from
the output (html, pdf, etc ).
Can you comment on this?

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

[Matias Capeletto]

On 6/26/07, Matias Capeletto <matias.capeletto@...> wrote:

> On 6/26/07, Matias Capeletto <matias.capeletto@...> wrote:
> > On 6/26/07, Rene Rivera <grafikrobot@...> wrote:
> > > Matias Capeletto wrote:
> > If I have understand your proposal, you want this layout:
> >
> > * doc/src/    ( Sources needed to generate the doc )
> >
> >     * doc/src/lib_name/lib_name.xml   ( dockbook docs )
> >     * doc/src/lib_name/lib_name.xsl    ( stylesheet )
> >     * doc/src/lib_name/Jamfile.v2        ( generate the docs inside
> > "doc/html/lib_name" )
> >
> >     * doc/src/lib_name/*.qbk ( quickbook source )
> >     * doc/src/lib_name/example/*.cpp ( used code samples )
>
> Having other things (html, pdf, style, etc) as my last mail, I want to
> know what are the pros of this layout for sources instead of the
> actual one:
>
> * libs/lib_name/doc/
>
>      * doc/lib_name/doc/lib_name.xml   ( dockbook docs )
>      * doc/lib_name/doc/lib_name.xsl    ( stylesheet )
>      * doc/lib_name/doc/Jamfile.v2        ( generate docs inside
> "doc/html/lib_name" )
>
>      * doc/lib_name/doc/*.qbk ( quickbook source )
>      * doc/lib_name/example/doc/*.cpp ( or doc/example )
>
> The thing I like about this layout is that everything a library author
> maintainer has to modify lives in "libs/lib_name". ( Not counting the
> files inside the boost headers directory, because that is a different
> business )
> I fail to see why the other scheme better separate the sources from
> the output (html, pdf, etc ).
> Can you comment on this?

Rene is a very busy at the moment. I will really miss his advice here.
Can others give us feedback about this subject?

Thanks!

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