mirror of https://github.com/CGAL/cgal
describe new header style
This commit is contained in:
Sylvain Pion
parent
8268a152f9
commit
df037e4ca3
|
|
@ -362,7 +362,8 @@ in contrast to the rules of previous paragraph.
|
|||
\ccIndexMainItemBegin{code format}
|
||||
|
||||
\begin{itemize}
|
||||
\item Lines should not exceed 80 characters.%
|
||||
\item Lines should not exceed 80 characters (the CVS server warns about that
|
||||
when committing)%
|
||||
\ccIndexSubitem{code format}{line length}
|
||||
\item Use indentation with at least two spaces extra per level.%
|
||||
\ccIndexSubitem{code format}{indentation}
|
||||
|
|
@ -381,9 +382,29 @@ in contrast to the rules of previous paragraph.
|
|||
\ccIndexSubitemBegin{source files}{headings for}
|
||||
|
||||
Each \cgal\ source file must start with a heading that allows for an easy
|
||||
identification of the file. The file header contains a copyright notice, the
|
||||
current release number and date, and a description of the file. The name of
|
||||
the file in the header should be relative to the \texttt{CGAL\_HOME} directory.
|
||||
identification of the file. The file header contains:
|
||||
\begin{itemize}
|
||||
\item a copyright notice, specifying all the years during which the file has
|
||||
been written or modified, as well as the owner(s) (typically the institutions
|
||||
employing the authors) of this work,
|
||||
\item the corresponding license (at the moment, only LGPL v2.1 and QPL v1.0
|
||||
are allowed in \cgal), and a pointer to the file containing its text in the
|
||||
\cgal\ distribution,
|
||||
\item a disclaimer notice,
|
||||
\item then, there are 4 keywords, which are automatically expanded by CVS
|
||||
(there are options to CVS to suppress these expansions if you need):
|
||||
\begin{itemize}
|
||||
\item \$Source$ : the name of the source file in the repository, it also
|
||||
helps figuring out which package the file comes from,
|
||||
\item \$Revision$ : the CVS revision of the file,
|
||||
\item \$Date$ : the date of this revision,
|
||||
\item \$Name$ : empty in general, otherwise contains the tag which has been
|
||||
used to checkout this file. It is used to identify the corresponding release
|
||||
of \cgal\ (internal or public).
|
||||
\end{itemize}
|
||||
\item Then the authors of (non-negligible parts of) this file are listed, with
|
||||
optional affiliation or e-mail address.
|
||||
\end{itemize}
|
||||
|
||||
\ccIndexSubitem{example programs}{headings for}
|
||||
\ccIndexSubitem{demo programs}{headings for}
|
||||
|
|
@ -395,6 +416,9 @@ the file realtive to the \texttt{CGAL\_HOME} directory
|
|||
so the file can be located when seen out of context (\eg, in the documentation
|
||||
or from the demos web page).
|
||||
|
||||
For the test-suite and the documentation source, these are not distributed at
|
||||
the moment, so there is no policy for now.
|
||||
|
||||
\InternalOnly{
|
||||
\input{code_format_internal}
|
||||
}
|
||||
|
|
|
|||
|
|
@ -1,127 +1,58 @@
|
|||
\subsection*{Internal releases}
|
||||
\ccIndexSubsubitemBegin{source files}{headings for}{internal releases}
|
||||
\subsection*{QPL version}
|
||||
\ccIndexSubsubitemBegin{source files}{headings for}{QPL version}
|
||||
|
||||
The heading of a \cgal\ source file that is submitted (for an internal release)
|
||||
should have the following format:
|
||||
Here follows what this gives for a file under the QPL :
|
||||
|
||||
\begin{verbatim}
|
||||
// ============================================================================
|
||||
// Copyright (c) 1999,2000,2001,2002 INRIA Sophia-Antipolis (France).
|
||||
// All rights reserved.
|
||||
//
|
||||
// Copyright (c) 1997-2001 The CGAL Consortium
|
||||
// This file is part of CGAL (www.cgal.org); you may redistribute it under
|
||||
// the terms of the Q Public License version 1.0.
|
||||
// See the file LICENSE.QPL distributed with CGAL.
|
||||
//
|
||||
// This software and related documentation is part of an INTERNAL release
|
||||
// of the Computational Geometry Algorithms Library (CGAL). It is not
|
||||
// intended for general use.
|
||||
// Licensees holding a valid commercial license may use this file in
|
||||
// accordance with the commercial license agreement provided with the software.
|
||||
//
|
||||
// ----------------------------------------------------------------------------
|
||||
// This file is provided AS IS with NO WARRANTY OF ANY KIND, INCLUDING THE
|
||||
// WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
|
||||
//
|
||||
// release : $CGAL_Revision$
|
||||
// release_date : $CGAL_Date$
|
||||
// $Source$
|
||||
// $Revision$ $Date$
|
||||
// $Name$
|
||||
//
|
||||
// file : include/CGAL/Min_ellipse_2.h
|
||||
// package : Min_ellipse_2 (3.5.4)
|
||||
// chapter : Geometric Optimisation
|
||||
//
|
||||
// source : web/Optimisation/Min_ellipse_2.aw
|
||||
// revision : $Revision$
|
||||
// revision_date : $Date$
|
||||
//
|
||||
// author(s) : Bernd Gaertner, Sven Schoenherr
|
||||
// maintainer : Sven Schoenherr <sven@inf.fu-berlin.de>
|
||||
// coordinator : ETH Zuerich (Bernd Gaertner <gaertner@inf.ethz.ch>)
|
||||
//
|
||||
// implementation: 2D Smallest Enclosing Ellipse
|
||||
// ============================================================================
|
||||
// Author(s) : Monique Teillaud <Monique.Teillaud@sophia.inria.fr>
|
||||
// Sylvain Pion <Sylvain.Pion@sophia.inria.fr>
|
||||
\end{verbatim}
|
||||
\ccIndexSubsubitemEnd{source files}{headings for}{QPL version}
|
||||
|
||||
The following rules apply to the fields:
|
||||
|
||||
\begin{itemize}
|
||||
\item {\tt <release>}, {\tt <release\_date>}, and {\tt <maintainer>} must be
|
||||
present but need not be filled in (since they will be overwritten when
|
||||
the internal release is created).
|
||||
\item {\tt <file>}, {\tt <package>}, {\tt <author(s)>}, and
|
||||
{\tt <coordinator>} are obligatory and must be filled in.
|
||||
\item {\tt <chapter>}, {\tt <source>}, {\tt <revision>}, {\tt <revision\_date>},
|
||||
and {\tt <implementation>} are optional.
|
||||
\item For the {\tt <coordinator>} field, the coordinating site as well as
|
||||
the person in charge is named, together with the person's e-mail address.
|
||||
\item Optionally, the next-to-last line may contain a comment on the
|
||||
functionality of the source file's content.
|
||||
\end{itemize}
|
||||
|
||||
When a new internal release is generated\ccIndexMainItem{internal release},
|
||||
the fields {\tt <release>} and {\tt <release\_date>} are overwritten.
|
||||
The release label for the internal release is composed of the number of the
|
||||
next public release, an~{\tt I} (for ``internal''), and a positive integer that
|
||||
represents the internal release number (\eg, e.g.~{\tt CGAL-2.2-I-1} was the
|
||||
number of the first internal release after public release 2.1).%
|
||||
\ccIndexSubitem{internal release}{number}
|
||||
If the field {\tt <maintainer>} is blank, it is filled in with the name and
|
||||
email address of the last person who submitted the package.%
|
||||
\ccIndexSubitem{\tt maintainer}{field in file header}
|
||||
All other fields between the two delimiting
|
||||
lines of equal signs remain untouched.
|
||||
\ccIndexSubsubitemEnd{source files}{headings for}{internal releases}
|
||||
|
||||
\subsection*{Public releases}
|
||||
\ccIndexSubsubitemBegin{source files}{headings for}{public releases}
|
||||
|
||||
When a new public release is generated, only the fields {\tt <file>},
|
||||
{\tt <package>}, \mbox{{\tt <chapter>}} (if present), and {\tt <author(s)>}
|
||||
are kept. The heading of the source file (generated by the
|
||||
\texttt{make\_public\_header} script
|
||||
(see Chapter~\ref{chap:releases})
|
||||
will become something like this:
|
||||
\subsection*{LGPL version}
|
||||
\ccIndexSubsubitemBegin{source files}{headings for}{LGPL version}
|
||||
|
||||
Here follows what this gives for a file under the LGPL :
|
||||
|
||||
\begin{verbatim}
|
||||
// ============================================================================
|
||||
//
|
||||
// Copyright (c) 1997-2000 The CGAL Consortium
|
||||
//
|
||||
// This software and related documentation is part of the
|
||||
// Computational Geometry Algorithms Library (CGAL).
|
||||
//
|
||||
// This software and documentation is provided "as-is" and without warranty
|
||||
// of any kind. In no event shall the CGAL Consortium be liable for any
|
||||
// damage of any kind.
|
||||
//
|
||||
// Every use of CGAL requires a license.
|
||||
//
|
||||
// Academic research and teaching license
|
||||
// - For academic research and teaching purposes, permission to use and copy
|
||||
// the software and its documentation is hereby granted free of charge,
|
||||
// provided that it is not a component of a commercial product, and this
|
||||
// notice appears in all copies of the software and related documentation.
|
||||
//
|
||||
// Commercial licenses
|
||||
// - A commercial license is available through Algorithmic Solutions,
|
||||
// (http://www.algorithmic-solutions.com).
|
||||
// - Commercial users may apply for an evaluation license by writing to
|
||||
// Algorithmic Solutions (contact@algorithmic-solutions.com).
|
||||
//
|
||||
// The CGAL Consortium consists of Utrecht University (The Netherlands),
|
||||
// Copyright (c) 2000,2001,2002,2003 Utrecht University (The Netherlands),
|
||||
// ETH Zurich (Switzerland), Freie Universitaet Berlin (Germany),
|
||||
// INRIA Sophia-Antipolis (France), Martin-Luther-University Halle-Wittenberg
|
||||
// (Germany), Max-Planck-Institute Saarbrucken (Germany), RISC Linz (Austria),
|
||||
// and Tel-Aviv University (Israel).
|
||||
// and Tel-Aviv University (Israel). All rights reserved.
|
||||
//
|
||||
// ----------------------------------------------------------------------------
|
||||
// This file is part of CGAL (www.cgal.org); you can redistribute it and/or
|
||||
// modify it under the terms of the GNU Lesser General Public License as
|
||||
// published by the Free Software Foundation; version 2.1 of the License.
|
||||
// See the file LICENSE.LGPL distributed with CGAL.
|
||||
//
|
||||
// release : CGAL-2.1
|
||||
// release_date : 2000, January 11
|
||||
// This file is provided AS IS with NO WARRANTY OF ANY KIND, INCLUDING THE
|
||||
// WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
|
||||
//
|
||||
// file : include/CGAL/Min_ellipse_2.h
|
||||
// package : Min_ellipse_2 (3.5.4)
|
||||
// chapter : Geometric Optimisation
|
||||
// author(s) : Bernd Gaertner, Sven Schoenherr
|
||||
// $Source$
|
||||
// $Revision$ $Date$
|
||||
// $Name$
|
||||
//
|
||||
// email : cgal@cs.uu.nl
|
||||
//
|
||||
// ============================================================================
|
||||
// Author(s) : Herve Bronnimann, Sylvain Pion
|
||||
\end{verbatim}
|
||||
\ccIndexSubsubitemEnd{source files}{headings for}{public releases}
|
||||
\ccIndexSubsubitemEnd{source files}{headings for}{LGPL version}
|
||||
\ccIndexSubitemEnd{source files}{headings for}
|
||||
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue