From 230a2c73aba2c8260a99d1b52e52ff94fa51f172 Mon Sep 17 00:00:00 2001 From: Vincent Richard Date: Tue, 5 Feb 2013 13:01:39 +0100 Subject: Updated book. Added build target for HTML using HeVeA. --- doc/book/.gitignore | 17 ++++++++ doc/book/Makefile | 18 +++++++-- doc/book/basics.tex | 4 +- doc/book/book.tex | 48 ++++++++++++++++------- doc/book/building.tex | 69 ++++++++++++++++++++------------- doc/book/images/messaging-services.svg | 30 +++++++------- doc/book/net.tex | 2 +- doc/book/start.tex | 19 +++++---- examples/Makefile | 8 ++++ examples/example1 | Bin 0 -> 7232240 bytes examples/example6 | Bin 0 -> 7165360 bytes 11 files changed, 140 insertions(+), 75 deletions(-) create mode 100644 doc/book/.gitignore create mode 100644 examples/Makefile create mode 100755 examples/example1 create mode 100755 examples/example6 diff --git a/doc/book/.gitignore b/doc/book/.gitignore new file mode 100644 index 00000000..5bb55842 --- /dev/null +++ b/doc/book/.gitignore @@ -0,0 +1,17 @@ +# PDFLatex +*.log +*.aux +*.toc +*.out +*.pdf +*.lo[flt] + +# Hevea +*.haux +*.htoc +book.image.tex +book.html + +images/Makefile2 +images/*.png + diff --git a/doc/book/Makefile b/doc/book/Makefile index 4c5aaae1..234a9643 100644 --- a/doc/book/Makefile +++ b/doc/book/Makefile @@ -1,19 +1,29 @@ -all: convert-images book +all: book convert-images: cd images ; make +book: book_pdf book_html + # Full build: multiple runs for correct references... -book: +book_pdf: convert-images pdflatex book.tex pdflatex book.tex pdflatex book.tex +book_html: convert-images + hevea book.tex + hevea book.tex + hevea book.tex + #latexml --path=/opt/local/share/texmf-texlive-dist/tex/latex/base/ --path=/opt/local/share/texmf-texlive-dist/tex/latex/mdwtools/ --path=/opt/local/share/texmf-texlive-dist/tex/latex/geometry/ --path=/opt/local/share/texmf-texlive-dist/tex/latex/ucs/ --path=/opt/local/share/texmf-texlive-dist/tex/latex/fancyhdr/ --path=/opt/local/share/texmf-texlive-dist/tex/latex/footmisc --destination book.xml book.tex + #latexmlpost --destination=book.html book.xml + # Only one run for development (faster) -book-dev: +book-dev: convert-images pdflatex book.tex clean: - rm -f *.toc *.aux *.lof *.log *.lol *.pdf + rm -f *.log *.aux *.toc *.out *.pdf *.lo[flt] + rm -f *.haux *.htoc book.image.tex book.html diff --git a/doc/book/basics.tex b/doc/book/basics.tex index 15d036d9..9c129912 100644 --- a/doc/book/basics.tex +++ b/doc/book/basics.tex @@ -296,7 +296,7 @@ grp->appendMailbox(mbox2); \begin{figure}[ht!] \center\includegraphics[width=0.7\textwidth] - {images/address-mailbox-mailboxgroup.png} + {images/address-mailbox-mailboxgroup.png}\endcenter \caption{Diagram for address-related classes} \label{uml_addr_mbox_mboxgroup} \end{figure} @@ -314,7 +314,7 @@ model is implemented in VMime, and all classes that take part in it. \begin{figure} \center\includegraphics[width=1.0\textwidth] - {images/message-body-header.png} + {images/message-body-header.png}\endcenter \caption{Overall structure of MIME messages} \label{uml_msg_body_header} \end{figure} diff --git a/doc/book/book.tex b/doc/book/book.tex index 4fccb360..4db213a3 100644 --- a/doc/book/book.tex +++ b/doc/book/book.tex @@ -1,31 +1,24 @@ \documentclass[11pt]{report} \title{{\Huge VMime Book} \\ \ \\ A Developer's Guide To VMime} -\author{Vincent Richard \\ vincent@vincent-richard.net} +\author{Vincent Richard \\ vincent@vmime.org} \usepackage{graphicx} \usepackage{tabularx} +\usepackage{array} \usepackage{listings} \usepackage[usenames]{color} \usepackage{ucs} -\usepackage[latin1]{inputenc} +\usepackage[utf8x]{inputenc} \usepackage[vcentering,dvips]{geometry} %\usepackage{type1cm} % scalable Computer Modern fonts \usepackage{courier} % use Adobe Courier instead of Computer Modern Typewriter \usepackage{fancyheadings} \usepackage{hyperref} -\usepackage{sverb} +\usepackage{verbatim} \usepackage{footmisc} -\addtolength{\parskip}{+0.3cm} -\linespread{1.05} - -\setlength{\skip\footins}{1cm} % margin between text and footnotes - -\clubpenalty=1000 -\widowpenalty=1000 - \setcounter{secnumdepth}{10} \setcounter{tocdepth}{10} @@ -40,12 +33,10 @@ \newcommand{\Chapter}[1]{\chapter{#1} \setcounter{figure}{1}} -% 'geometry' configuration -\geometry{papersize={210mm,297mm},total={160mm,230mm}} - % 'listings' configuration \definecolor{listingFrame}{rgb}{0.9,0.9,0.9} \lstset{language=C++,showstringspaces=false} +\lstset{keywordstyle=\bf,commentstyle=\it} \lstset{captionpos=b,extendedchars=true,inputencoding=latin1} \lstset{fontadjust=true,basewidth={0.5em,0.4em},columns=fixed,flexiblecolumns=false} \lstset{frame=leftline,framerule=0.1cm,framesep=0.3cm,rulecolor=\color{listingFrame}} @@ -57,6 +48,27 @@ breaklinks=true,urlcolor=blue,linkcolor=black,bookmarks=true,bookmarksopen=true } +% HTML output configuration +%HEVEA\renewcommand{\includegraphics}[2][]{\imgsrc{#2}} +%HEVEA\renewcommand{\verti}[1]{#1} +%HEVEA\def\vdot{\bullet} +%HEVEA\newcommand{\linespread}{} +%HEVEA\newcommand{\clubpenalty}{} +%HEVEA\newcommand{\widowpenalty}{} +%HEVEA\newcommand{\geometry}{} + + +% Page layout +\geometry{papersize={210mm,297mm},total={160mm,230mm}} + +% Text layout +\setlength{\skip\footins}{1cm} % margin between text and footnotes +\clubpenalty=1000 +\addtolength{\parskip}{+0.3cm} +\linespread{1.05} +\widowpenalty=1000 + + \begin{document} % Title page @@ -78,6 +90,9 @@ \thispagestyle{empty} \ \newpage + +%HEVEA\begin{comment} + % List of listings \lstlistoflistings \addcontentsline{toc}{chapter}{Listings} @@ -90,11 +105,14 @@ \listoftables \addcontentsline{toc}{chapter}{List of tables} +%HEVEA\end{comment} + + % Appendixes \appendix \chapter{The GNU General Public License\label{appendix_license}} -\verbinput{../../COPYING} +\verbatiminput{../../COPYING} \end{document} diff --git a/doc/book/building.tex b/doc/book/building.tex index 7011373c..c96e95db 100644 --- a/doc/book/building.tex +++ b/doc/book/building.tex @@ -15,13 +15,13 @@ To build VMime from the sources, you will need the following: \begin{itemize} \item a working C++ compiler with good STL implementation and also a good support for templates (for example, \href{http://gcc.gnu.org/}{GNU GCC}) ; -\item \href{http://www.scons.org/}{SCons} build system, or the -autoconf/automake tool chain ; +\item \href{http://www.cmake.org/}{CMake} build system ; \item an usable iconv() implementation (see \href{http://www.gnu.org/software/libiconv/}{libiconv of GNU Project}) ; \item the \href{http://www.gnu.org/software/gsasl/}{GNU SASL Library} if you want SASL\footnote{Simple Authentication and Security Layer} support ; -\item the \href{http://www.gnu.org/software/gnutls/}{GNU TLS Library} if you +\item either the \href{http://www.openssl.org}{OpenSSL library} or the +\href{http://www.gnu.org/software/gnutls/}{GNU TLS Library} if you want SSL and TLS\footnote{Transport Layer Security} support ; \end{itemize} @@ -31,49 +31,62 @@ want SSL and TLS\footnote{Transport Layer Security} support ; You can download a package containing the source files of the latest release of the VMime library from the \href{http://www.vmime.org/}{VMime web site}. -You can also obtain the current development version from the CVS. VMime's CVS -repository can be checked out from anonymous CVS with the following -instructions. When prompted for a password for {\em anonymous}, simply press -Enter key. +You can also obtain the current development version from the Git repository, +which is currently hosted at GitHub. It can be checked out through anonymous +access with the following instruction: \begin{verbatim} - cvs -d:pserver:anonymous@cvs.vmime.org:/cvsroot/vmime login - cvs -z3 -d:pserver:anonymous@cvs.vmime.org:/cvsroot/vmime co -P vmime + git clone git://github.com/kisli/vmime \end{verbatim} % ============================================================================ \section{Compiling and installing} There are two possibilities for compiling VMime: using SCons building system, -or using the Autotools. - -\vnote{MS Visual C++ users, you can skip this section as a project file -is provided in the distribution tarball.} +or using CMake. SCons is only used for development purposes, and so it is recommended that you -use Autotools to build the project as it is a more portable solution, and is +use CMake to build the project as it is a more portable solution, and is likely to work out-of-the-box on your computer. Thus, we will not describe the process of compiling VMime using SCons here. -\vnote{Windows users, you can use MinGW and MSYS\footnote{See on the MinGW -website: http://www.mingw.org/} to install a POSIX compatible environment -on top of Windows. This allow executing configure scripts and Makefiles on -Windows}. +CMake is an open source, cross-platform build system. It will generate all +build scripts required to compile VMime on your platform. -Before compiling VMime, you should run the {\vcode configure} script to -detect some parameters specific to your platform. Go into the directory where -you extracted the tarball and type: +First, from the directory where you extracted the tarball or checked out +the sources, run {\vcode cmake} with the {\vcode -G} argument corresponding +to your platform. For example, if you are on a Unix-compatible platform (like +GNU/Linux or MacOS), type: \begin{verbatim} - $ ./configure + $ cmake -G "Unix Makefiles" \end{verbatim} -This will create a file named {\vcode config.hpp} in the {\vcode vmime/} -directory, with the parameters detected for your platform. You should modify -this file only if you know what you are doing! +This will perform some tests on your system to check for libs installed +and some platform-specific includes. It will then create a Makefile in +the root directory of VMime. + +\vnote{Delete the {\vcode CMakeCache.txt} file if something changed on your +system, as CMake may cache some values to speed up things.} + +This will also create a file named {\vcode config.hpp} in the {\vcode vmime/} +directory, with the parameters detected for your platform. You should not +modify this file directly. Instead, you can run again {\vcode cmake} and +specify your own defines on the command line. + +For example, to force using OpenSSL library instead of GnuTLS for TLS +support, type: + +\begin{verbatim} + $ cmake -G "Unix Makefiles" -DVMIME_TLS_SUPPORT_LIB_IS_OPENSSL=ON \ + -DVMIME_TLS_SUPPORT_LIB_IS_GNUTLS=OFF +\end{verbatim} If you want to enable or disable some features in VMime, you can obtain some -help by typing {\vcode ./configure --help}. The defaults should be OK though. +help by typing {\vcode cmake -L}. The defaults should be OK though. + +For more information about using CMake, go to +\href{http://www.cmake.org/}{the CMake web site}. Next, you can start the compilation process: @@ -84,8 +97,8 @@ Next, you can start the compilation process: Please wait a few minutes will the compilation runs (you should have some time to have a coffee right now!). If you get errors during the compilation, be sure your system meet the requirements given at the beginning of the chapter. -You can also try to get a newer version (from the CVS, for example) or to -get some help on VMime user forums. +You can also try to get a newer version (from the Git repository, for example) +or to get some help on VMime user forums. If everything has been compiled successfully, you can install the library and the development files on your system: diff --git a/doc/book/images/messaging-services.svg b/doc/book/images/messaging-services.svg index 69d5f870..fe4f8c8e 100644 --- a/doc/book/images/messaging-services.svg +++ b/doc/book/images/messaging-services.svg @@ -1,23 +1,24 @@ + + inkscape:export-ydpi="74.639999" + version="1.1"> + inkscape:window-x="69" + inkscape:window-y="33" + showgrid="false" + inkscape:window-maximized="0" /> @@ -604,13 +607,6 @@ id="path5436" d="M 325.97175,390.06210 L 661.85821,390.06210" style="fill:none;fill-opacity:0.75000000;fill-rule:evenodd;stroke:#000000;stroke-width:1.2515085;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-opacity:1.0000000" /> - $ and use the following line +{\vcode vmime/platforms/windows/windowsHandler.hpp} and use the following line to initialize the platform handler: \begin{lstlisting} @@ -102,6 +101,10 @@ vmime::platform:: setHandler (); \end{lstlisting} +\vnote{since version 0.9.2, this is not needed any more: the platform +handler is installed automatically using the platform detected during the +build configuration.} + \vnote{since version 0.8.1, {\vcode vmime::platformDependant} was renamed to {\vcode vmime::platform}. The old name has been kept for compatibility but it is recommended that you update your code, if needed.} diff --git a/examples/Makefile b/examples/Makefile new file mode 100644 index 00000000..640ba253 --- /dev/null +++ b/examples/Makefile @@ -0,0 +1,8 @@ +all: example1 example6 + +example1: example1.cpp ../libvmime-debug.a + g++-mp-4.8 -o example1 example1.cpp -I.. ../libvmime-debug.a -L /opt/local/lib -lgnutls -lgsasl -liconv + +example6: example6.cpp ../libvmime-debug.a + g++-mp-4.8 -o example6 example6.cpp -I.. ../libvmime-debug.a -L /opt/local/lib -lgnutls -lgsasl -liconv + diff --git a/examples/example1 b/examples/example1 new file mode 100755 index 00000000..f56835fa Binary files /dev/null and b/examples/example1 differ diff --git a/examples/example6 b/examples/example6 new file mode 100755 index 00000000..28db9401 Binary files /dev/null and b/examples/example6 differ -- cgit v1.2.3