/usr/include/regina-normal/docs.h is in regina-normal-dev 4.96-2.1build2.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 | /**************************************************************************
* *
* Regina - A Normal Surface Theory Calculator *
* Computational Engine *
* *
* Copyright (c) 1999-2014, Ben Burton *
* For further details contact Ben Burton (bab@debian.org). *
* *
* This program is free software; you can redistribute it and/or *
* modify it under the terms of the GNU General Public License as *
* published by the Free Software Foundation; either version 2 of the *
* License, or (at your option) any later version. *
* *
* As an exception, when this program is distributed through (i) the *
* App Store by Apple Inc.; (ii) the Mac App Store by Apple Inc.; or *
* (iii) Google Play by Google Inc., then that store may impose any *
* digital rights management, device limits and/or redistribution *
* restrictions that are required by its terms of service. *
* *
* This program is distributed in the hope that it will be useful, but *
* WITHOUT ANY WARRANTY; without even the implied warranty of *
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU *
* General Public License for more details. *
* *
* You should have received a copy of the GNU General Public *
* License along with this program; if not, write to the Free *
* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, *
* MA 02110-1301, USA. *
* *
**************************************************************************/
/* end stub */
/*! \file docs.h
* \brief Contains miscellaneous documentation.
*/
/*! \mainpage
*
* <center><b>
* Regina<br>
* Software for 3-manifold topology and normal surface theory<br>
* Copyright © 1999-2014, The Regina development team
* </b></center>
*
* This documentation describes the functions, classes and related
* entities in the C++ calculation engine, as well as how these can
* be accessed through Python.
*
* This API documentation is written in terms of C++.
* However, Python programmers can use exactly the same functions,
* classes, methods and so on. If the Python version of a function
* differs from the C++ version, you will see a bold <b>Python:</b> note
* telling you how it differs.
*
* To start: visit the <a href="modules.html">Modules</a> page and take
* a look around, or browse through the classes regina::NTriangulation and
* regina::NNormalSurfaceList.
*
* <h3>Citation</h3>
*
* If you find Regina useful in your research, please consider citing it as
* you would any other paper that you use. A suggested form of reference is:
*
* Benjamin A. Burton, Ryan Budney, William Pettersson, et al.,
* "Regina: Software for 3-manifold topology and normal surface theory",
* http://regina.sourceforge.net/ , 1999-2014.
*
* <h3>Authors</h3>
*
* The primary developers of Regina are:
* <ul>
* <li>Benjamin Burton <bab@debian.org></li>
* <li>Ryan Budney <rybu@uvic.ca></li>
* <li>William Pettersson <william.pettersson@gmail.com></li>
* </ul>
* <p>
* Many others have been of assistance with this project, be it through
* time, knowledge, testing or code. Please see the full list of
* acknowledgements in the users' handbook.
*
* <h3>Copying and Modification</h3>
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation; either version 2 of the License, or
* (at your option) any later version.
*
* Some of this code comes with additional permissions; see the
* section below regarding online distribution.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program; if not, write to the Free Software
* Foundation, Inc., 51 Franklin St, Fifth Floor, Boston,
* MA 02110-1301, USA.
*
* <h3>Online Distribution</h3>
*
* Regina's own source code comes with the following permissions in
* addition to the GNU General Public License:
*
* As an exception, when this program is distributed through (i) the
* App Store by Apple Inc.; (ii) the Mac App Store by Apple Inc.; or
* (iii) Google Play by Google Inc., then that store may impose any
* digital rights management, device limits and/or redistribution
* restrictions that are required by its terms of service.
*
* Some third-party libraries included in Regina are not granted this
* exception, and must be removed from any build that is distributed on
* stores that cannot comply with the GNU General Public License (such as
* Apple's App Store). See the third-party licenses below for details.
*
* <h3>SnapPea and SnapPy</h3>
*
* Regina includes portions of the SnapPea kernel and its successor SnapPy,
* which it uses for some geometric calculations. The SnapPea kernel was
* written by Jeff Weeks, and SnapPy was written by Marc Culler, Nathan
* Dunfield, and others. SnapPy and the corresponding SnapPea kernel are
* distributed under the terms of the GNU General Public License, version 2
* or any later version, as published by the Free Software Foundation.
*
* <h3>Normaliz Library</h3>
*
* Regina includes a copy of libnormaliz, which it uses to help with the
* enumeration of fundamental normal surfaces. Normaliz was written by
* Winfried Bruns, Bogdan Ichim and Christof Soeger. It is distributed
* under the terms of the GNU General Public License as published by the
* Free Software Foundation, either version 3 of the License, or (at your
* option) any later version.
*
* <h3>Orb Kernel</h3>
*
* Regina includes snippets of code from Orb, for use in importing and
* exporting files in Orb / Casson format. Orb is based on SnapPea
* (see above) with additional code written by Damian Heard, who has also
* given permission for his code to be distributed under the terms of the
* GNU General Public License.
*/
/*! \page i18n Encodings for international strings
*
* As of version 4.5, Regina (finally) pays attention to character encodings.
*
* The calculation engine uses UTF-8 for all strings (except possibly
* for filenames; see below). This means that programmers who pass
* strings \e into routines must ensure that they use UTF-8, and
* programmers who receive strings \e from routines may assume that
* they are returned in UTF-8. Note that plain ASCII is a subset of
* UTF-8, so plain ASCII text is always fine to use.
*
* Regina's XML data files are also stored using UTF-8. Older
* versions of Regina used LATIN1 (the default for the Qt libraries)
* and did not specify an encoding in the XML header; however, Regina's
* file I/O routines are aware of this, and will convert older data into
* UTF-8 as it is loaded into memory (the files themselves are
* of course not modified). The routine versionUsesUTF8() may be
* useful for programmers who need to work with older data files at a
* low level.
*
* File \e names are a special case, since here Regina must interact with
* the underlying operating system. All filenames that are passed into
* routines must be presented in whatever encoding the operating system
* expects; Regina will simply pass them through to the standard C/C++ file
* I/O routines (such as fopen() or std::ifstream::open()) without modifying
* them in any way.
*
* It should be noted that ancient data files that use the old binary
* format (Regina 2.x, before mid-2002) only support plain ASCII text.
* Support for the old binary format is likely to be removed entirely in the
* very near future.
*
* \ifacespython Users and programmers who use the Python interface must
* take special care, since Python does not pass strings around in UTF-8
* by default.
*
* Proper support for character encodings is quite new, and the main
* author rarely uses this (being a native English speaker). If you
* see Regina treating international characters in unexpected ways,
* please mail the author(s) or file a bug report so the problem can be
* fixed!
*/
|