[boost] How to handle generated html files with modular-boost and GIT?

Subject: [boost] How to handle generated html files with modular-boost and GIT?
From: Paul A. Bristow (pbristow_at_[hidden])
Date: 2014-06-20 07:28:46

I've started to proof-read Vladimir Batov's Boost.Convert library and correct a
(very few) typos etc.

I've had some troublesome experience with building docs with Boost.Math and this
is similar (but much smaller).

Can experienced GIT users suggest how better to handle the problem of generated
files in the /html folder.

I've provided below a log of what I've done after a single edit to a Quickbook
file.

As you will see, there are *new* files (with randomized filenames)

html/boost/convert_id274115.html
 html/boost/convert_id274279.html
 html/boost/convert_id277698.html
 html/boost/convert_id277857.html

(and also my log file cv_20jun14_1135.log)

And all the .html file have been modified.

So what do I do?

I'd hope just to be able to GIT commit  (but there will be added files so "git
commit -a") and "git push".

(But what about obsolete files like html/boost/convert_id999999.html that should
be deleted?) .

This seems a muddle, so should we remove the /html folder from GIT using
gitignore?

However this would mean that users would have to generate the html (and assumes
that all the tools like Doxygen and autoIndex are setup right - an unwelcome
requirement).

And what about .log files - it seems very useful and reasonable to have them
live in /doc but be ignored by  GIT?

Could/Should there be a global entry in top level /modular-boost/.gitignore to
exclude all .log files?

(I'd also like to put .bat or .sh files to build docs etc here too - there are
various options in building and automatically dated log files are nice to have.
)

Suggestions on how better to manage this?

Paul

I:\modular-boost>cd ./libs/convert/doc

I:\modular-boost\libs\convert\doc>dir
 Volume in drive I is Boost
 Volume Serial Number is FAC6-FCC3

 Directory of I:\modular-boost\libs\convert\doc

19-Jun-14  18:07    <DIR>          .
19-Jun-14  18:07    <DIR>          ..
19-Jun-14  18:07             1,413 00_main.qbk
19-Jun-14  18:07                28 98_ref.qbk
19-Jun-14  18:07                16 99_index.qbk
19-Jun-14  18:07             1,158 acknowledgments.qbk
19-Jun-14  18:07               175 algorithms.qbk
19-Jun-14  18:07             1,729 converters.qbk
19-Jun-14  18:07            17,528 convert_ref.xml
19-Jun-14  18:07            10,730 design_notes.qbk
19-Jun-14  18:07               133 generate-html.sh
19-Jun-14  18:07             2,337 getting_serious.qbk
19-Jun-14  18:07             2,848 getting_started.qbk
19-Jun-14  18:07    <DIR>          html
19-Jun-14  18:07               357 index.idx
19-Jun-14  18:07             2,601 introduction.qbk
19-Jun-14  18:07             3,060 Jamfile.v2
19-Jun-14  18:07             1,254 lexcast_converter.qbk
19-Jun-14  18:07             1,228 other.qbk
19-Jun-14  18:07             8,427 performance.qbk
19-Jun-14  18:07             1,789 rationale.qbk
19-Jun-14  18:07               220 references.qbk
19-Jun-14  18:07             1,627 return_value.qbk
19-Jun-14  18:07             5,431 scratchpad.txt
19-Jun-14  18:07             4,372 sstream_converter.qbk
              22 File(s)         68,461 bytes
               3 Dir(s)  99,253,600,256 bytes free

I:\modular-boost\libs\convert\doc>b2 -a --enable-index > cv_20jun14_1135.log

I:\modular-boost\libs\convert\doc>git status
On branch develop
Your branch is up-to-date with 'origin/develop'.

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git checkout -- <file>..." to discard changes in working directory)

        modified:   convert_ref.xml
        modified:   html/boost/cnv/adapter.html
        modified:   html/boost/cnv/base.html
        modified:   html/boost/cnv/basic_stringstream.html
        modified:   html/boost/cnv/lexical_cast.html
        modified:   html/boost/cnv/notation.html
        modified:   html/boost/cnv/printf.html
        modified:   html/boost/cnv/spirit.html
        modified:   html/boost/cnv/strtol.html
        modified:   html/boost/throw_on_failure.html
        modified:   html/boost/throw_on_failure_type.html
        modified:   html/boostbook.css
        modified:   html/convert_reference.html
        modified:   html/docutils.css
        modified:   html/header/boost/convert/lexical_cast_hpp.html
        modified:   html/header/boost/convert/parameters_hpp.html
        modified:   html/header/boost/convert/printf_hpp.html
        modified:   html/header/boost/convert/spirit_hpp.html
        modified:   html/header/boost/convert/sstream_hpp.html
        modified:   html/header/boost/convert/strtol_hpp.html
        modified:   html/header/boost/make_default_hpp.html
        modified:   html/index.html
        modified:   html/index/s17.html
        modified:   html/minimal.css
        modified:   html/standalone_HTML.manifest
        modified:   html/the_boost_convert_library/acknowledgements.html
        modified:   html/the_boost_convert_library/better_error_detection.html
        modified:
html/the_boost_convert_library/boost__lexical_cast_based_converter.html
        modified:
html/the_boost_convert_library/boost_convert_performance_overhead.html
        modified:
html/the_boost_convert_library/boost_convert_with_standard_algorithms.html
        modified:   html/the_boost_convert_library/converters.html
        modified:   html/the_boost_convert_library/design_notes.html
        modified:
html/the_boost_convert_library/design_notes/converter_signature.html
        modified:
html/the_boost_convert_library/design_notes/todo_converter_parameter_related_con
siderations__explicit__default__globally_set__others_.html
        modified:
html/the_boost_convert_library/design_notes/todo_converter_pluggability.html
        modified:
html/the_boost_convert_library/design_notes/user_interface_signature.html
        modified:   html/the_boost_convert_library/getting_started.html
        modified:
html/the_boost_convert_library/getting_started/basic_error_processing.html
        modified:
html/the_boost_convert_library/getting_started/flexibility_and_adaptability_to_c
hange.html
        modified:   html/the_boost_convert_library/introduction.html
        modified:   html/the_boost_convert_library/other_conversions.html
        modified:   html/the_boost_convert_library/performance.html
        modified:   html/the_boost_convert_library/references.html
        modified:   html/the_boost_convert_library/return_value.html
        modified:
html/the_boost_convert_library/std__stringstream_based_converter.html
        modified:
html/the_boost_convert_library/std__stringstream_based_converter/integration_of_
user_defined_types.html
        modified:
html/the_boost_convert_library/std__stringstream_based_converter/locale_support.
html
        modified:
html/the_boost_convert_library/std__stringstream_based_converter/the___default_c
onstructible__type_requirement.html
        modified:   introduction.qbk

Untracked files:
  (use "git add <file>..." to include in what will be committed)

        cv_20jun14_1135.log
        html/boost/convert_id274115.html
        html/boost/convert_id274279.html
        html/boost/convert_id277698.html
        html/boost/convert_id277857.html
        html/boost/convert_id285317.html
        html/boost/convert_id285442.html

no changes added to commit (use "git add" and/or "git commit -a")