Commit bc707fdb authored by Aron Helser's avatar Aron Helser

Build doc improvements - lessen duplication, make consistent.

The README.md file included incomplete build instructions -
shortened them, and included some details in build.md instead.
Also added suggestion for obtaining 'make' on windows.
parent c94a38c2
Pipeline #27711 passed with stage
......@@ -21,8 +21,9 @@ is as follows:
3. Clone the repository:
$ git clone https://gitlab.kitware.com/paraview/paraview-guide-ce.git ParaViewGuide
$ cd ParaViewGuide
$ mkdir ParaViewGuide; cd ParaViewGuide
$ git clone https://gitlab.kitware.com/paraview/paraview-guide-ce.git src
$ cd src
The main repository will be configured as your `origin` remote.
4. Add your fork as a the `gitlab` remote.
......@@ -32,6 +33,10 @@ is as follows:
5. Install dependencies and [build][build.md]
$ mkdir ../build; cd ../build
$ ccmake ../src
$ make
6. Edit files and create commits (repeat as needed):
$ git checkout -b my-topic origin/master
......
......@@ -965,8 +965,9 @@ automatically created if you apply a filter that needs this view, e.g., the
\begin{didyouknow}
If you generate lengthy data for the \ui{Line Chart View}, the default variables
that are selected may be slow to adjust. You can change \paraview's default
behavior and load no variables at all by selecting the \ui{Load No Chart Variables}
checkbox under \ui{Settings/General/Properties Panel Options}.
behavior to initially load no variables at all by selecting the
\ui{Load No Chart Variables} checkbox under
\ui{Settings/General/Properties Panel Options}.
\begin{center}
\includegraphics[width=0.4\linewidth]{Images/ChartNoVarSetting.png}
......
......@@ -35,35 +35,15 @@ The printed editions of **The ParaView Guide** are released under [CC BY-ND 4.0]
Build Instructions
------------------
This is **CMake** based project and can be built similar to ParaView. We use **LaTeX**
for typesetting the guides. Thus, unless you are familiar with setting up LaTeX on your system,
This is a **CMake** based project and follows some of the same steps as building [ParaView][]. We use **LaTeX** for typesetting the guides. Thus, unless you are familiar with setting up LaTeX on your system,
you may want to simply download the pregenerated PDF from the [ParaView homepage][ParaView Books].
1. Clone the repository
Please see [CONTRIBUTING.md][] for detailed instructions on git, and [build.md][] for instructions on setting up prerequisites and building.
$ git clone https://gitlab.kitware.com/paraview/paraview-guide-ce.git ParaViewGuide
The main repository will be configured as your `origin` remote.
On a successful build, the **ParaView/ParaViewUsersGuide.pdf** and/or **ParaViewCatalyst/ParaViewCatalystUsersGuide.pdf** will be generated.
2. Run CMake. This step requires you have LaTeX (and necessary modules) installed
on your system. You can turn **ENABLE_PARAVIEW_GUIDE** (default: ON) and/or
**ENABLE_CATALYST_USERS_GUIDE** (default: OFF) ON or OFF based on your preference.
On Unix-based systems, the steps are:
$ mkdir ParaViewGuildBuild
$ cmake <PATH>/ParaViewGuide
$ make
3. On successful build, the **ParaView/ParaViewUsersGuide.pdf** and/or
**ParaViewCatalyst/ParaViewCatalystUsersGuide.pdf** will be generated based
on the options you chose in Step 2.
Note that Step 2 can take a long time, especially *rendering* the images.
To speed things, you can edit [ParaViewUsersGuide.tex][] file to change
the documentclass mode to `[draft]`.
\documentclass[draft]{InsightSoftwareGuide}
This will generate the the draft PDF without any images.
[ParaViewUsersGuide.tex]: ParaView/ParaViewUsersGuide.tex
[build.md]: build.md
[ParaView]: https://gitlab.kitware.com/paraview/paraview/blob/master/CONTRIBUTING.md
Reporting Bugs
---------------
......
Build ParaViewGuide
===================
The ParaView Guide Community Edition is a LaTeX document used to generate a final .pdf file. The Catalyst User's Guide can be built at the same time, in the same way.
The ParaView Guide Community Edition is a **LaTeX** document that uses **CMake** to generate a final .pdf file. The Catalyst User's Guide can be built at the same time, in the same way.
## Prerequisites
You need CMake, LaTeX, and ImageMagick.
You need CMake, Make, LaTeX, and ImageMagick.
### CMake
* See the [ParaView docs][] for obtaining CMake.
### Windows
* To get LaTex, install [MikTeX][]
- First, run the MiKTex Update (Admin). You may have to run twice if it updates the updater binary.
- MikTex Package Manager (admin), search and install packages:
* To get LaTex, install [MiKTeX][]
- First, run the MiKTeX Update (Admin). You may have to run twice if it updates the updater binary.
- MiKTeX Package Manager (Admin), search and install packages:
> adjustbox, bclogo, catoptions, cite, collectbox, colortbl, enumitem, etoolbox, fancyhdr, floatflt, fncychap, frankenstein, ifoddpage, l3kernel, l3packages, listings, mdframed, mptopdf, ms, paralist, pgf, setspace, subfigure, symbol, url, wrapfig, xcolor, xstring
+ Unfortunately MikTeX automatic install during build doesn't seem to work. If you discover a missing package during build, please add it to this list.
+ Unfortunately MiKTeX automatic install during build doesn't seem to work. If you discover a missing package during build, please add it to this list.
+ [mpm][] command line looks like a good option to do this all at once.
* Install [ImageMagick][], use the recommended download (Q16 precision is fine)
- In the installer, choose 'Install legacy utilities (convert)'
* Make. I suggest using 'Git Bash' from [Git for Windows][], and adding the [MinGW][] binaries, which include `make`, to your path.
### Linux (Ubuntu)
* To get LaTeX, install a TeXLive package. I tried this, on Ubuntu:
......@@ -26,21 +27,44 @@ You need CMake, LaTeX, and ImageMagick.
* ImageMagick seems to be installed by default on Ubuntu.
## Run Cmake
If you created a ParaViewGuide/src and ParaViewGuide/build directory, and you cloned the repository into src, then:
* `cd build`
* `cmake-gui ../src` or `ccmake ../src`
- click 'configure'
- You may change whether to build the ParaView Guide and/or the Catalyst User's Guide.
- Generator: I chose the 'MSYS makefiles' generator, after I added MinGW binaries to the path in my Git Bash shell.
- Click 'Advanced'. MIKTEX_BINARY_PATH should be set to something like "C:/Program Files (x86)/MiKTeX 2.9/miktex/bin/" to allow all the LaTeX binaries to be found.
- You may have to manually set the IMAGEMAGICK_CONVERT path, to something like "C:/Program Files/ImageMagick-7.0.3-Q16/convert.exe", if it complains about finding Windows convert.exe instead.
Follow the instructions in [CONTRIBUTING.md][] to clone the repository.
If you clone like this:
$ mkdir ParaViewGuide; cd ParaViewGuide
$ git clone https://gitlab.kitware.com/paraview/paraview-guide-ce.git src
then:
$ mkdir build; cd build
$ cd build
$ cmake-gui ../src -or- ccmake ../src
* click 'configure'
* You may change whether to build the ParaView Guide and/or the Catalyst User's Guide by changing the options **ENABLE_PARAVIEW_GUIDE** (default: ON) and/or **ENABLE_CATALYST_USERS_GUIDE** (default: OFF)
* Generator: I chose the 'MSYS makefiles' generator, after I added MinGW binaries to the path in my Git Bash shell.
* Click 'Advanced'. MIKTEX_BINARY_PATH should be set to something like "C:/Program Files (x86)/MiKTeX 2.9/miktex/bin/" to allow all the LaTeX binaries to be found.
* You may have to manually set the IMAGEMAGICK_CONVERT path, to something like "C:/Program Files/ImageMagick-7.0.3-Q16/convert.exe", if it complains about finding Windows convert.exe instead.
## Build
* `make`
- If any packages are missing, MiKTex will offer to fetch them. However, this failed for me. Copy the package name from the missing .sty dialong, and then in the main MiKTex Package Manager, search for the package name and install it. Build again.
- You will have to build at least twice, so that references can be updated correctly. You will see many warnings during the build process.
$ make
* If any packages are missing, MiKTeX will offer to fetch them. However, this failed for me. Copy the package name from the missing .sty dialog, and then in the main MiKTeX Package Manager, search for the package name and install it. Build again.
* You will have to build at least twice, so that references can be updated correctly. You will see many warnings during the build process.
* On a successful build, the **ParaView/ParaViewUsersGuide.pdf** and/or **ParaViewCatalyst/ParaViewCatalystUsersGuide.pdf** will be generated based on the options you chose in cmake.
Note that `make` can take a long time, especially *rendering* the images.
To speed things, you can edit [ParaViewUsersGuide.tex][] file to change
the documentclass mode to `[draft]`.
\documentclass[draft]{InsightSoftwareGuide}
This will generate the the draft PDF without any images.
[CONTRIBUTING.md]: CONTRIBUTING.md
[Git for Windows]: https://git-scm.com/downloads
[ImageMagick]: http://www.imagemagick.org/script/binary-releases.php
[MikTeX]: http://miktex.org/howto/install-miktex
[MinGW]: http://www.mingw.org/wiki/Getting_Started
[mpm]: http://docs.miktex.org/manual/mpm.html
[ParaView docs]: https://gitlab.kitware.com/paraview/paraview/blob/master/CONTRIBUTING.md
[ParaViewUsersGuide.tex]: ParaView/ParaViewUsersGuide.tex
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment