On Mon, Feb 27, 2012 at 10:29 AM, Tom Browder <[email protected]> wrote:
> On Sun, Feb 26, 2012 at 23:38, Clifford Yapp <[email protected]> wrote:
> ...
> >> Looks like a fix didn't work--still get the message. It seems to me
> >> we need an INSTALL.in file that's versioned and let cmake construct
> >> the unversioned INSTALL from it plus its addidions from the
> >> CMakeLists.txt files.
> >
> >
> > Crud - copy/paste error - sorry. Give 49561 a try.
>
> Okay, that works--no error message.
>
> Cliff, I slept on this and I propose another look at this whole
> doc/xtradoc//html/pdf issue: I am very confused with the current build
> state and doc options.
>
> 1. Somewhere in INSTALL or HACKING we need to tell users what they
> need to produce pdf. There mention any environment variables that
> affect the process (such as APACHE_FOP).
>
Here is the current intent:
BRLCAD_EXTRADOCS is the top level control - with it ON, documentation is
generated according to the other options. With it off, no DocBook
processing takes place (not even the html man pages.)
The following three options control the three forms of output DocBook might
generate:
BRLCAD_EXTRADOCS_HTML
BRLCAD_EXTRADOCS_MAN
BRLCAD_EXTRADOCS_PDF
All three of these options are present anad visible to the user ONLY if
BRLCAD_EXTRADOCS is enabled.
For MSVC, MAN output makes no sense and is disabled. The PDF option is
only available if APACHE_FOP is defined.
Because producing PDFs for the man pages takes so long, there is an extra
variable BRLCAD_EXTRADOCS_PDF_MAN that defaults to the same value as
BRLCAD_EXTRADOCS_PDF, but may be turned off even if BRLCAD_EXTRADOCS_PDF is
on - this lets a build produce PDFs for the articles and books without the
full slog of the man pages.
Remember, we have to keep the toplevel README and INSTALL files succinct -
if we need more detailed DocBook specific descriptions, they should
probably be in the docbook readme with a pointer to that file from the
toplevel.
> As an aside:
>
> + I also think that ALL input files versioned for the cmake system
> should be named *.in (except, of course, for CMakeLists.txt) and any
> generated files under our control should be named *.cmake.autogen and
> be eligible to be blown away (and also ignored by subversion).
>
Um. What files are you talking about here?
+ We should also have some separate doc make targets, e.g., "doc", "pdf",
> etc.
>
That might be possible... I'll do a few experiments.
>
> 2. From my experiments with the current revision (49561), the doc
> options are these (in order as I visualize a natural sequence):
>
> a. man+xtra: html <== BRLCAD_EXTRADOCS=ON (default)
>
What do you mean with "man+xtra"? All docbook documentation, including man
pages, is "extra".
> b. man: html <== BRLCAD_EXTRADOCS=OFF
>
I'm not following you here - with BRLCAD_EXTRADOCS off, there is (or should
be) no DocBook processing at all, even html man pages.
> c. man+xtra: html, pdf <== BRLCAD_EXTRADOCS_PDF=ON
>
(if BRLCAD_EXTRADOCS=ON as well)
d. man+xtra: html
> xtra: pdf <== BRLCAD_EXTRADOCS_PDF_MAN=OFF
> (seems to require BRLCAD_EXTRADOCS_PDF=ON)
>
Yes - BRLCAD_EXTRADOCS_PDF_MAN is a way to refine BRLCAD_EXTRADOCS_PDF.
> Output from cmake for those options:
>
> a. Generate extra docs ...................: ON (man/html only)
> b. Generate extra docs ...................: OFF
> c. Generate extra docs ...................: ON (man/html/pdf)
> d. Generate extra docs ...................: ON (man/html/pdf)
>
Right.
>
> I don't see any practical reason to generate man or extra docs html
> alone so I eliminate one of the above.
? I'm not following you here...
> I think the options should be
> renamed to reflect a more natural sequence, something like this (none
> require any of the others to be ON):
>
> a. man+xtra: html <== BRLCAD_ALLDOCS=ON
> (default)
> b. a + man+xtra: pdf <== BRLCAD_ALLDOCS_PDF=ON
> (default OFF)
> c. a + xtra: pdf <== BRLCAD_EXTRADOCS_PDF=ON
> (default OFF)
> d: no docs <== BRLCAD_ALLDOCS=OFF
>
> Output from cmake would be something like:
>
> a. Generate docs ................: man+xtra: html
> b. Generate docs ................: man+xtra: html, pdf
> c. Generate docs ................: man: html; xtra: html, pdf
> d. Generate docs ................: OFF
>
> And if a user chooses a pdf option and cmake can't find the required
> files, the user should be notified what is missing.
>
I'm a bit confused trying to follow your notation... does my initial
explanation of the current options clear anything up?
Thoughts?
>
I agree that more "high-level" DocBook targets would be nice, but other
than that I'm not quite following what you want to change from the current
behavior.
Cheers,
Cliff
------------------------------------------------------------------------------
Try before you buy = See our experts in action!
The most comprehensive online learning library for Microsoft developers
is just $99.99! Visual Studio, SharePoint, SQL - plus HTML5, CSS3, MVC3,
Metro Style Apps, more. Free future releases when you subscribe now!
http://p.sf.net/sfu/learndevnow-dev2
_______________________________________________
BRL-CAD Developer mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/brlcad-devel
