[Asterisk-code-review] README: Convert to README.md. (asterisk[15])

Corey Farrell asteriskteam at digium.com
Tue Nov 21 09:11:54 CST 2017


Corey Farrell has uploaded this change for review. ( https://gerrit.asterisk.org/7345


Change subject: README: Convert to README.md.
......................................................................

README: Convert to README.md.

Convert the README file to markdown format, remove the old README.  This
causes websites like github to display the README in a much nicer
format with live links.  The raw file is still very readable from
plain text editors and terminals.

Change-Id: I7d13131764a9a9026e5f8a6ddb245a01bbd788e7
---
D README
A README.md
2 files changed, 272 insertions(+), 296 deletions(-)



  git pull ssh://gerrit.asterisk.org:29418/asterisk refs/changes/45/7345/1

diff --git a/README b/README
deleted file mode 100644
index a1ccf2c..0000000
--- a/README
+++ /dev/null
@@ -1,296 +0,0 @@
-===============================================================================
-===                     The Asterisk(R) Open Source PBX
-===
-===                   by Mark Spencer <markster at digium.com>
-===                  and the Asterisk.org developer community
-===
-===                    Copyright (C) 2001-2016 Digium, Inc.
-===                       and other copyright holders.
-===============================================================================
-
--------------------------------------------------------------------------------
---- SECURITY ------------------------------------------------------------------
-
-  It is imperative that you read and fully understand the contents of
-the security information document before you attempt to configure and run
-an Asterisk server.
-
-  If you downloaded Asterisk as a tarball, see the security section in the PDF
-version of the documentation in doc/tex/asterisk.pdf.  Alternatively, pull up
-the HTML version of the documentation in doc/tex/asterisk/index.html.  The
-source for the security document is available in doc/tex/security.tex.
--------------------------------------------------------------------------------
-
--------------------------------------------------------------------------------
---- WHAT IS ASTERISK ? --------------------------------------------------------
-
-  Asterisk is an Open Source PBX and telephony toolkit.  It is, in a
-sense, middleware between Internet and telephony channels on the bottom,
-and Internet and telephony applications at the top.  However, Asterisk supports
-more telephony interfaces than just Internet telephony.  Asterisk also has a
-vast amount of support for traditional PSTN telephony, as well.  For more
-information on the project itself, please visit the Asterisk home page at:
-
-           https://www.asterisk.org
-
-  The official Asterisk wiki can be found at:
-
-           https://wiki.asterisk.org
-
-  In addition you'll find lots of information compiled by the Asterisk
-community on this Wiki:
-
-           https://www.voip-info.org/wiki-Asterisk
-
-  There is a book on Asterisk published by O'Reilly under the Creative Commons
-License. It is available in book stores as well as in a downloadable version on
-the http://www.asteriskdocs.org web site.
--------------------------------------------------------------------------------
-
--------------------------------------------------------------------------------
---- SUPPORTED OPERATING SYSTEMS -----------------------------------------------
-
---- Linux
-  The Asterisk Open Source PBX is developed and tested primarily on the
-GNU/Linux operating system, and is supported on every major GNU/Linux
-distribution.
-
---- Others
-  Asterisk has also been 'ported' and reportedly runs properly on other
-operating systems as well, including Sun Solaris, Apple's Mac OS X, Cygwin,
-and the BSD variants.
--------------------------------------------------------------------------------
-
--------------------------------------------------------------------------------
---- GETTING STARTED -----------------------------------------------------------
-
-  First, be sure you've got supported hardware (but note that you don't need
-ANY special hardware, not even a sound card) to install and run Asterisk.
-
-  Supported telephony hardware includes:
-
-	* All Analog and Digital Interface cards from Digium (www.digium.com)
-	* QuickNet Internet PhoneJack and LineJack (http://www.quicknet.net)
-	* any full duplex sound card supported by ALSA, OSS, or PortAudio
-	* any ISDN card supported by mISDN on Linux
-	* The Xorcom Astribank channel bank
-	* VoiceTronix OpenLine products
-
--------------------------------------------------------------------------------
-
--------------------------------------------------------------------------------
---- UPGRADING FROM AN EARLIER VERSION -----------------------------------------
-
-  If you are updating from a previous version of Asterisk, make sure you
-read the UPGRADE.txt file in the source directory. There are some files
-and configuration options that you will have to change, even though we
-made every effort possible to maintain backwards compatibility.
-
-  In order to discover new features to use, please check the configuration
-examples in the /configs directory of the source code distribution.  For a
-list of new features in this version of Asterisk, see the CHANGES file.
--------------------------------------------------------------------------------
-
--------------------------------------------------------------------------------
---- NEW INSTALLATIONS ---------------------------------------------------------
-
-  Ensure that your system contains a compatible compiler and development
-libraries.  Asterisk requires either the GNU Compiler Collection (GCC) version
-3.0 or higher, or a compiler that supports the C99 specification and some of
-the gcc language extensions.  In addition, your system needs to have the C
-library headers available, and the headers and libraries for ncurses.
-
-  There are many modules that have additional dependencies.  To see what
-libraries are being looked for, see ./configure --help, or run
-"make menuselect" to view the dependencies for specific modules.
-
-  On many distributions, these dependencies are installed by packages with names
-like 'glibc-devel', 'ncurses-devel', 'openssl-devel' and 'zlib-devel'
-or similar.
-
-  So, let's proceed:
-
-1) Read this README file.
-
-  There are more documents than this one in the doc/ directory.  You may also
-want to check the configuration files that contain examples and reference
-guides. They are all in the configs/ directory.
-
-2) Run "./configure"
-
-  Execute the configure script to guess values for system-dependent
-variables used during compilation.
-
-3) Run "make menuselect" [optional]
-
-  This is needed if you want to select the modules that will be compiled and to
-check dependencies for various optional modules.
-
-4) Run "make"
-
-  Assuming the build completes successfully:
-
-5) Run "make install"
-
-  If this is your first time working with Asterisk, you may wish to install
-the sample PBX, with demonstration extensions, etc.  If so, run:
-
-6) "make samples"
-
-  Doing so will overwrite any existing configuration files you have installed.
-
-  Finally, you can launch Asterisk in the foreground mode (not a daemon) with:
-
-# asterisk -vvvc
-
-  You'll see a bunch of verbose messages fly by your screen as Asterisk
-initializes (that's the "very very verbose" mode).  When it's ready, if
-you specified the "c" then you'll get a command line console, that looks
-like this:
-
-*CLI>
-
-  You can type "core show help" at any time to get help with the system.  For help
-with a specific command, type "core show help <command>".  To start the PBX using
-your sound card, you can type "console dial" to dial the PBX.  Then you can use
-"console answer", "console hangup", and "console dial" to simulate the actions
-of a telephone.  Remember that if you don't have a full duplex sound card
-(and Asterisk will tell you somewhere in its verbose messages if you do/don't)
-then it won't work right (not yet).
-
-  "man asterisk" at the Unix/Linux command prompt will give you detailed
-information on how to start and stop Asterisk, as well as all the command
-line options for starting Asterisk.
-
-  Feel free to look over the configuration files in /etc/asterisk, where you
-will find a lot of information about what you can do with Asterisk.
--------------------------------------------------------------------------------
-
--------------------------------------------------------------------------------
---- ABOUT CONFIGURATION FILES -------------------------------------------------
-
-  All Asterisk configuration files share a common format.  Comments are
-delimited by ';' (since '#' of course, being a DTMF digit, may occur in
-many places).  A configuration file is divided into sections whose names
-appear in []'s.  Each section typically contains two types of statements,
-those of the form 'variable = value', and those of the form 'object =>
-parameters'.  Internally the use of '=' and '=>' is exactly the same, so
-they're used only to help make the configuration file easier to
-understand, and do not affect how it is actually parsed.
-
-  Entries of the form 'variable=value' set the value of some parameter in
-asterisk.  For example, in dahdi.conf, one might specify:
-
-	switchtype=national
-
-  In order to indicate to Asterisk that the switch they are connecting to is
-of the type "national".  In general, the parameter will apply to
-instantiations which occur below its specification.  For example, if the
-configuration file read:
-
-	switchtype = national
-	channel => 1-4
-	channel => 10-12
-	switchtype = dms100
-	channel => 25-47
-
-  The "national" switchtype would be applied to channels one through
-four and channels 10 through 12, whereas the "dms100" switchtype would
-apply to channels 25 through 47.
-
-  The "object => parameters" instantiates an object with the given
-parameters.  For example, the line "channel => 25-47" creates objects for
-the channels 25 through 47 of the card, obtaining the settings
-from the variables specified above.
--------------------------------------------------------------------------------
-
--------------------------------------------------------------------------------
---- SPECIAL NOTE ON TIME ------------------------------------------------------
-
-  Those using SIP phones should be aware that Asterisk is sensitive to
-large jumps in time.  Manually changing the system time using date(1)
-(or other similar commands) may cause SIP registrations and other
-internal processes to fail.  If your system cannot keep accurate time
-by itself use NTP (http://www.ntp.org/) to keep the system clock
-synchronized to "real time".  NTP is designed to keep the system clock
-synchronized by speeding up or slowing down the system clock until it
-is synchronized to "real time" rather than by jumping the time and
-causing discontinuities. Most Linux distributions include precompiled
-versions of NTP.  Beware of some time synchronization methods that get
-the correct real time periodically and then manually set the system
-clock.
-
-  Apparent time changes due to daylight savings time are just that,
-apparent.  The use of daylight savings time in a Linux system is
-purely a user interface issue and does not affect the operation of the
-Linux kernel or Asterisk.  The system clock on Linux kernels operates
-on UTC.  UTC does not use daylight savings time.
-
-  Also note that this issue is separate from the clocking of TDM
-channels, and is known to at least affect SIP registrations.
--------------------------------------------------------------------------------
-
--------------------------------------------------------------------------------
---- FILE DESCRIPTORS ----------------------------------------------------------
-
-  Depending on the size of your system and your configuration,
-Asterisk can consume a large number of file descriptors.  In UNIX,
-file descriptors are used for more than just files on disk.  File
-descriptors are also used for handling network communication
-(e.g. SIP, IAX2, or H.323 calls) and hardware access (e.g. analog and
-digital trunk hardware).  Asterisk accesses many on-disk files for
-everything from configuration information to voicemail storage.
-
-  Most systems limit the number of file descriptors that Asterisk can
-have open at one time.  This can limit the number of simultaneous
-calls that your system can handle.  For example, if the limit is set
-at 1024 (a common default value) Asterisk can handle approximately 150
-SIP calls simultaneously.  To change the number of file descriptors
-follow the instructions for your system below:
--------------------------------------------------------------------------------
-
--------------------------------------------------------------------------------
---- PAM-based Linux System ----------------------------------------------------
-
-  If your system uses PAM (Pluggable Authentication Modules) edit
-/etc/security/limits.conf.  Add these lines to the bottom of the file:
-
-root            soft    nofile          4096
-root            hard    nofile          8196
-asterisk        soft    nofile          4096
-asterisk        hard    nofile          8196
-
-(adjust the numbers to taste).  You may need to reboot the system for
-these changes to take effect.
-
-== Generic UNIX System ==
-
-  If there are no instructions specifically adapted to your system
-above you can try adding the command "ulimit -n 8192" to the script
-that starts Asterisk.
--------------------------------------------------------------------------------
-
--------------------------------------------------------------------------------
---- MORE INFORMATION ----------------------------------------------------------
-
-  See the doc directory for more documentation on various features. Again,
-please read all the configuration samples that include documentation on
-the configuration options.
-
-  If this release of Asterisk was downloaded from a tarball, then some
-additional documentation should have been included.
-     * doc/tex/asterisk.pdf --- PDF version of the documentation
-     * doc/tex/asterisk/index.html --- HTML version of the documentation
-
-  Finally, you may wish to visit the web site and join the mailing list if
-you're interested in getting more information.
-
-   https://www.asterisk.org/support
-
-  Welcome to the growing worldwide community of Asterisk users!
--------------------------------------------------------------------------------
-
---- Mark Spencer, and the Asterisk.org development community
-
--------------------------------------------------------------------------------
-Asterisk is a trademark of Digium, Inc.
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..4ed9b3e
--- /dev/null
+++ b/README.md
@@ -0,0 +1,272 @@
+# The Asterisk(R) Open Source PBX
+```text
+        By Mark Spencer <markster at digium.com> and the Asterisk.org developer community.
+        Copyright (C) 2001-2016 Digium, Inc. and other copyright holders.
+```
+## SECURITY
+
+  It is imperative that you read and fully understand the contents of
+the security information document before you attempt to configure and run
+an Asterisk server.
+
+  If you downloaded Asterisk as a tarball, see the security section in the PDF
+version of the documentation in doc/tex/asterisk.pdf.  Alternatively, pull up
+the HTML version of the documentation in doc/tex/asterisk/index.html.  The
+source for the security document is available in doc/tex/security.tex.
+
+## WHAT IS ASTERISK ?
+
+  Asterisk is an Open Source PBX and telephony toolkit.  It is, in a
+sense, middleware between Internet and telephony channels on the bottom,
+and Internet and telephony applications at the top.  However, Asterisk supports
+more telephony interfaces than just Internet telephony.  Asterisk also has a
+vast amount of support for traditional PSTN telephony, as well.
+
+  For more information on the project itself, please visit the Asterisk
+[home page] and the official [wiki].  In addition you'll find lots
+of information compiled by the Asterisk community at [voip-info.org].
+
+  There is a book on Asterisk published by O'Reilly under the Creative Commons
+License. It is available in book stores as well as in a downloadable version on
+the [asteriskdocs.org] web site.
+
+## SUPPORTED OPERATING SYSTEMS
+
+### Linux
+
+  The Asterisk Open Source PBX is developed and tested primarily on the
+GNU/Linux operating system, and is supported on every major GNU/Linux
+distribution.
+
+### Others
+
+  Asterisk has also been 'ported' and reportedly runs properly on other
+operating systems as well, including Sun Solaris, Apple's Mac OS X, Cygwin,
+and the BSD variants.
+
+## GETTING STARTED
+
+  First, be sure you've got supported hardware (but note that you don't need
+ANY special hardware, not even a sound card) to install and run Asterisk.
+
+Supported telephony hardware includes:
+* All Analog and Digital Interface cards from [Digium]
+* QuickNet Internet PhoneJack and LineJack (http://www.quicknet.net)
+* any full duplex sound card supported by ALSA, OSS, or PortAudio
+* any ISDN card supported by mISDN on Linux
+* The Xorcom Astribank channel bank
+* VoiceTronix OpenLine products
+
+### UPGRADING FROM AN EARLIER VERSION
+
+  If you are updating from a previous version of Asterisk, make sure you
+read the [UPGRADE.txt] file in the source directory. There are some files
+and configuration options that you will have to change, even though we
+made every effort possible to maintain backwards compatibility.
+
+  In order to discover new features to use, please check the configuration
+examples in the [configs] directory of the source code distribution.  For a
+list of new features in this version of Asterisk, see the [CHANGES] file.
+
+### NEW INSTALLATIONS
+
+  Ensure that your system contains a compatible compiler and development
+libraries.  Asterisk requires either the GNU Compiler Collection (GCC) version
+3.0 or higher, or a compiler that supports the C99 specification and some of
+the gcc language extensions.  In addition, your system needs to have the C
+library headers available, and the headers and libraries for ncurses.
+
+  There are many modules that have additional dependencies.  To see what
+libraries are being looked for, see `./configure --help`, or run
+`make menuselect` to view the dependencies for specific modules.
+
+  On many distributions, these dependencies are installed by packages with names
+like 'glibc-devel', 'ncurses-devel', 'openssl-devel' and 'zlib-devel'
+or similar.
+
+So, let's proceed:
+1. Read this file.
+
+  There are more documents than this one in the [doc] directory.  You may also
+want to check the configuration files that contain examples and reference
+guides in the [configs] directory.
+
+2. Run `./configure`
+
+  Execute the configure script to guess values for system-dependent
+variables used during compilation.
+
+3. Run `make menuselect` _\[optional]_
+
+  This is needed if you want to select the modules that will be compiled and to
+check dependencies for various optional modules.
+
+4. Run `make`
+
+Assuming the build completes successfully:
+
+5. Run `make install`
+
+  If this is your first time working with Asterisk, you may wish to install
+the sample PBX, with demonstration extensions, etc.  If so, run:
+
+6. Run `make samples`
+
+  Doing so will overwrite any existing configuration files you have installed.
+
+7. Finally, you can launch Asterisk in the foreground mode (not a daemon) with:
+```
+        # asterisk -vvvc
+```
+  You'll see a bunch of verbose messages fly by your screen as Asterisk
+initializes (that's the "very very verbose" mode).  When it's ready, if
+you specified the "c" then you'll get a command line console, that looks
+like this:
+```
+        *CLI>
+```
+  You can type "core show help" at any time to get help with the system.  For help
+with a specific command, type "core show help <command>".  To start the PBX using
+your sound card, you can type "console dial" to dial the PBX.  Then you can use
+"console answer", "console hangup", and "console dial" to simulate the actions
+of a telephone.  Remember that if you don't have a full duplex sound card
+(and Asterisk will tell you somewhere in its verbose messages if you do/don't)
+then it won't work right (not yet).
+
+  "man asterisk" at the Unix/Linux command prompt will give you detailed
+information on how to start and stop Asterisk, as well as all the command
+line options for starting Asterisk.
+
+  Feel free to look over the configuration files in `/etc/asterisk`, where you
+will find a lot of information about what you can do with Asterisk.
+
+### ABOUT CONFIGURATION FILES
+
+  All Asterisk configuration files share a common format.  Comments are
+delimited by ';' (since '#' of course, being a DTMF digit, may occur in
+many places).  A configuration file is divided into sections whose names
+appear in []'s.  Each section typically contains two types of statements,
+those of the form 'variable = value', and those of the form 'object =>
+parameters'.  Internally the use of '=' and '=>' is exactly the same, so
+they're used only to help make the configuration file easier to
+understand, and do not affect how it is actually parsed.
+
+  Entries of the form 'variable=value' set the value of some parameter in
+asterisk.  For example, in [chan_dahdi.conf], one might specify:
+```
+	switchtype=national
+```
+  In order to indicate to Asterisk that the switch they are connecting to is
+of the type "national".  In general, the parameter will apply to
+instantiations which occur below its specification.  For example, if the
+configuration file read:
+```
+	switchtype = national
+	channel => 1-4
+	channel => 10-12
+	switchtype = dms100
+	channel => 25-47
+```
+
+  The "national" switchtype would be applied to channels one through
+four and channels 10 through 12, whereas the "dms100" switchtype would
+apply to channels 25 through 47.
+
+  The "object => parameters" instantiates an object with the given
+parameters.  For example, the line "channel => 25-47" creates objects for
+the channels 25 through 47 of the card, obtaining the settings
+from the variables specified above.
+
+### SPECIAL NOTE ON TIME
+
+  Those using SIP phones should be aware that Asterisk is sensitive to
+large jumps in time.  Manually changing the system time using date(1)
+(or other similar commands) may cause SIP registrations and other
+internal processes to fail.  If your system cannot keep accurate time
+by itself use [NTP] to keep the system clock
+synchronized to "real time".  NTP is designed to keep the system clock
+synchronized by speeding up or slowing down the system clock until it
+is synchronized to "real time" rather than by jumping the time and
+causing discontinuities. Most Linux distributions include precompiled
+versions of NTP.  Beware of some time synchronization methods that get
+the correct real time periodically and then manually set the system
+clock.
+
+  Apparent time changes due to daylight savings time are just that,
+apparent.  The use of daylight savings time in a Linux system is
+purely a user interface issue and does not affect the operation of the
+Linux kernel or Asterisk.  The system clock on Linux kernels operates
+on UTC.  UTC does not use daylight savings time.
+
+  Also note that this issue is separate from the clocking of TDM
+channels, and is known to at least affect SIP registrations.
+
+### FILE DESCRIPTORS
+
+  Depending on the size of your system and your configuration,
+Asterisk can consume a large number of file descriptors.  In UNIX,
+file descriptors are used for more than just files on disk.  File
+descriptors are also used for handling network communication
+(e.g. SIP, IAX2, or H.323 calls) and hardware access (e.g. analog and
+digital trunk hardware).  Asterisk accesses many on-disk files for
+everything from configuration information to voicemail storage.
+
+  Most systems limit the number of file descriptors that Asterisk can
+have open at one time.  This can limit the number of simultaneous
+calls that your system can handle.  For example, if the limit is set
+at 1024 (a common default value) Asterisk can handle approximately 150
+SIP calls simultaneously.  To change the number of file descriptors
+follow the instructions for your system below:
+
+#### PAM-BASED LINUX SYSTEM
+
+  If your system uses PAM (Pluggable Authentication Modules) edit
+`/etc/security/limits.conf`.  Add these lines to the bottom of the file:
+```text
+root            soft    nofile          4096
+root            hard    nofile          8196
+asterisk        soft    nofile          4096
+asterisk        hard    nofile          8196
+```
+
+(adjust the numbers to taste).  You may need to reboot the system for
+these changes to take effect.
+
+#### GENERIC UNIX SYSTEM
+
+  If there are no instructions specifically adapted to your system
+above you can try adding the command `ulimit -n 8192` to the script
+that starts Asterisk.
+
+## MORE INFORMATION
+
+  See the [doc] directory for more documentation on various features.
+Again, please read all the configuration samples that include documentation
+on the configuration options.
+
+  Finally, you may wish to visit the [support] site and join the [mailing
+list] if you're interested in getting more information.
+
+Welcome to the growing worldwide community of Asterisk users!
+```
+        Mark Spencer, and the Asterisk.org development community
+```
+
+---
+
+Asterisk is a trademark of Digium, Inc.
+
+[home page]: https://www.asterisk.org
+[support]: https://www.asterisk.org/support
+[wiki]: https://wiki.asterisk.org/
+[mailing list]: http://lists.digium.com/mailman/listinfo/asterisk-users
+[chan_dahdi.conf]: configs/samples/chan_dahdi.conf.sample
+[voip-info.org]: http://www.voip-info.org/wiki-Asterisk
+[asteriskdocs.org]: http://www.asteriskdocs.org
+[NTP]: http://www.ntp.org/
+[Digium]: https://www.digium.com/
+[UPGRADE.txt]: UPGRADE.txt
+[CHANGES]: CHANGES
+[configs]: configs
+[doc]: doc
+

-- 
To view, visit https://gerrit.asterisk.org/7345
To unsubscribe, visit https://gerrit.asterisk.org/settings

Gerrit-Project: asterisk
Gerrit-Branch: 15
Gerrit-MessageType: newchange
Gerrit-Change-Id: I7d13131764a9a9026e5f8a6ddb245a01bbd788e7
Gerrit-Change-Number: 7345
Gerrit-PatchSet: 1
Gerrit-Owner: Corey Farrell <git at cfware.com>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.digium.com/pipermail/asterisk-code-review/attachments/20171121/7c522169/attachment-0001.html>


More information about the asterisk-code-review mailing list