[syslinux:elflink] txt/: Add new AsciiDoc formatted documentation
syslinux-bot for Gene Cumm
gene.cumm at gmail.com
Thu Jan 24 09:45:04 PST 2013
Commit-ID: 857bfbd30639862ec4c1e49e84893c978de06c6f
Gitweb: http://www.syslinux.org/commit/857bfbd30639862ec4c1e49e84893c978de06c6f
Author: Gene Cumm <gene.cumm at gmail.com>
AuthorDate: Thu, 6 Dec 2012 23:43:01 -0500
Committer: Gene Cumm <gene.cumm at gmail.com>
CommitDate: Thu, 17 Jan 2013 21:28:28 -0500
txt/: Add new AsciiDoc formatted documentation
Signed-off-by: Gene Cumm <gene.cumm at gmail.com>
---
txt/.gitignore | 7 +
txt/Makefile | 108 ++++++++++
txt/com-bug.txt | 11 +
txt/com-name.txt | 12 ++
txt/com-rpt.txt | 22 ++
txt/hello.txt | 16 ++
txt/syslinux-cli.txt | 65 ++++++
txt/syslinux.cfg.txt | 564 +++++++++++++++++++++++++++++++++++++++++++++++++++
txt/syslinux.txt | 217 ++++++++++++++++++++
9 files changed, 1022 insertions(+)
diff --git a/txt/.gitignore b/txt/.gitignore
new file mode 100644
index 0000000..55c6041
--- /dev/null
+++ b/txt/.gitignore
@@ -0,0 +1,7 @@
+*.1
+*.5
+*.html
+*.pdf
+*.text
+*.xml
+docbook-xsl.css
diff --git a/txt/Makefile b/txt/Makefile
new file mode 100644
index 0000000..11f1225
--- /dev/null
+++ b/txt/Makefile
@@ -0,0 +1,108 @@
+## -----------------------------------------------------------------------
+##
+## Copyright 2012 Gene Cumm
+##
+## Some logic from win32/Makefile:
+## Copyright 1998-2008 H. Peter Anvin - All Rights Reserved
+## Copyright 2010 Intel Corporation; author: H. Peter Anvin
+##
+## 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, Inc., 53 Temple Place Ste 330,
+## Boston MA 02111-1307, USA; either version 2 of the License, or
+## (at your option) any later version; incorporated herein by reference.
+##
+## -----------------------------------------------------------------------
+
+##
+## AsciiDoc documentation for syslinux
+##
+
+topdir = ..
+MAKEDIR = $(topdir)/mk
+# include $(MAKEDIR)/embedded.mk
+
+A2X_OPTS = -k
+# A2X_OPTS += -v
+A2X_MAN_OPTS = -D man -f manpage
+
+DOCS = syslinux.txt syslinux-cli.txt syslinux.cfg.txt
+MAN_DOCS = man/syslinux.1 man/syslinux-cli.1 man/syslinux.cfg.5
+HTML_DOCS := $(patsubst %.txt,html/%.html,$(DOCS))
+XHTML_DOCS := $(patsubst %.txt,%.html,$(DOCS))
+# MAN_DOCS := $(patsubst %.txt,man/%.1,$(DOCS1)) $(patsubst %.txt,man/%.5,$(DOCS5))
+TEXT_DOCS := $(patsubst %.txt,%.text,$(DOCS))
+PDF_DOCS := $(patsubst %.txt,%.pdf,$(DOCS))
+TARGETS =
+
+# ASCIIDOC_OK := $(shell which asciidoc 2>&1 ; echo $$?)
+ASCIIDOC_OK := $(shell which asciidoc > /dev/null ; echo $$?)
+A2X_XML_OK := $(shell a2x $(A2X_OPTS) -f docbook hello.txt 2>&1 ; echo $$?)
+ifeq ($(A2X_XML_OK),0)
+A2X_MAN_OK := $(shell a2x $(A2X_MAN_OPTS) hello.txt 2>&1 ; echo $$?)
+A2X_XHTML_OK := $(shell a2x $(A2X_OPTS) -f xhtml hello.xml 2>&1 ; echo $$?)
+A2X_TEXT_OK := $(shell a2x $(A2X_OPTS) -f text hello.xml 2>&1 ; echo $$?)
+endif
+
+ifeq ($(ASCIIDOC_OK),0)
+TARGETS += $(HTML_DOCS)
+endif
+ifeq ($(A2X_MAN_OK),0)
+TARGETS += $(MAN_DOCS)
+endif
+ifeq ($(A2X_XHTML_OK),0)
+TARGETS += $(XHTML_DOCS)
+endif
+ifeq ($(A2X_TEXT_OK),0)
+TARGETS += $(TEXT_DOCS)
+endif
+
+# $(HTML_DOCS) $(MAN_DOCS) $(XHTML_DOCS) $(TEXT_DOCS)
+all: $(TARGETS)
+
+syslinux.cfg.txt: com-bug.txt com-rpt.txt
+
+# During 'make all', *.xml is kept but deleted at the end; do we _really_
+# need the XML longer?
+.PRECIOUS: %.xml
+
+# %.html: %.txt
+# asciidoc -D html $<
+
+html/%.html: %.txt
+ asciidoc -o $@ $<
+
+# As of AsciiDoc-8.5.2, altering the output filename for a2x does not appear possible
+# xhtml/%.html: %.txt
+# a2x $(A2X_OPTS) -D xhtml -f xhtml $<
+# text/%.text: %.xml %.txt
+# a2x $(A2X_OPTS) -D text -f text $<
+
+%.xml: %.txt
+ a2x $(A2X_OPTS) -f docbook $<
+
+# when %.xml is missing, an update to %.txt must force regeneration
+%.html: %.xml %.txt
+ a2x $(A2X_OPTS) -f xhtml $<
+
+man/%.1: %.txt
+ a2x $(A2X_MAN_OPTS) $<
+
+man/%.5: %.txt
+ a2x $(A2X_MAN_OPTS) $<
+
+%.text: %.xml %.txt
+ a2x $(A2X_OPTS) -f text $<
+
+%.pdf: %.xml %.txt
+ a2x $(A2X_OPTS) -f pdf $<
+
+tidy dist:
+ rm -f *~ *.xml *.text.html text/*.text.html text/*.xml xhtml/*.xml
+
+clean: tidy
+
+spotless: clean
+ rm -f *.1 *.5 *.css *.html *.text html/*.html man/*.1 man/*.5 text/*.text xhtml/*.html xhtml/*.css
+
+-include .*.d
diff --git a/txt/com-bug.txt b/txt/com-bug.txt
new file mode 100644
index 0000000..f16139a
--- /dev/null
+++ b/txt/com-bug.txt
@@ -0,0 +1,11 @@
+
+// == KNOWN BUGS ==
+
+Several known bugs/common problems are listed at
+http://www.syslinux.org/wiki/index.php/Common_Problems and known
+hardware compatibility issues are listed at
+http://www.syslinux.org/wiki/index.php/Hardware_Compatibility with
+filename translation difficulty and early PXE stacks being some of the
+most common. Reporting of other encountered issues is welcome and
+appreciated.
+
diff --git a/txt/com-name.txt b/txt/com-name.txt
new file mode 100644
index 0000000..b24811f
--- /dev/null
+++ b/txt/com-name.txt
@@ -0,0 +1,12 @@
+
+// == NAMING CONVENTION ==
+
+As of 3.73, a standard for naming conventions was adopted to more
+clearly distinguish different aspects. The moniker "The *Syslinux*
+Project", in standard proper noun capitalization, shall be used to refer
+to the project as a whole. The all-caps form shall be used to refer to a
+particular loader variant such as "*SYSLINUX*" for the standard disk
+(floppy/hard disk; formerly just FAT) loader. The all-lower case form
+should be used to refer to a particular installer such as
+"syslinux-mtools" for the mtools-based installer for *SYSLINUX*.
+
diff --git a/txt/com-rpt.txt b/txt/com-rpt.txt
new file mode 100644
index 0000000..fe368ee
--- /dev/null
+++ b/txt/com-rpt.txt
@@ -0,0 +1,22 @@
+
+// == BUG REPORTS ==
+
+I would appreciate hearing of any problems you have with Syslinux. I
+would also like to hear from you if you have successfully used Syslinux,
+*especially* if you are using it for a distribution.
+
+If you are reporting problems, please include all possible information
+about your system and your BIOS; the vast majority of all problems
+reported turn out to be BIOS or hardware bugs, and I need as much
+information as possible in order to diagnose the problems.
+
+There is a mailing list for discussion among Syslinux users and for
+announcements of new and test versions. To join, or to browse the
+archive, go to:
+
+http://www.zytor.com/mailman/listinfo/syslinux
+
+Please DO NOT send HTML messages or attachments to the mailing list
+(including multipart/alternative or similar.) All such messages will be
+bounced.
+
diff --git a/txt/hello.txt b/txt/hello.txt
new file mode 100644
index 0000000..3757627
--- /dev/null
+++ b/txt/hello.txt
@@ -0,0 +1,16 @@
+= hello(1) =
+:doctype: manpage
+:author: World Greeter
+:author-email: hello at domain.local
+:revdate: 1970-01-01
+:data-uri:
+
+
+== NAME ==
+hello - hello world
+
+== SYNOPSIS ==
+hello
+
+== Description ==
+Say hello and greet the world
diff --git a/txt/syslinux-cli.txt b/txt/syslinux-cli.txt
new file mode 100644
index 0000000..c0affc4
--- /dev/null
+++ b/txt/syslinux-cli.txt
@@ -0,0 +1,65 @@
+= syslinux-cli(1) =
+:doctype: manpage
+:revdate: 2012-11-10
+:author: H. Peter Anvin
+:author-email: hpa at zytor.com
+:editor1: Gene Cumm
+:editor1-email: gene.cumm at gmail.com
+:editor1-revlast: 2012-11-10
+:data-uri:
+
+== NAME ==
+syslinux-cli - *Syslinux* boot prompt/command line interface
+
+
+== DESCRIPTION ==
+*Syslinux*'s boot prompt provides a very simplistic command line
+interface for loading modules and booting kernels.
+
+
+== BOOT PROMPT ==
+=== COMMAND LINE KEYSTROKES ===
+The command line prompt supports the following keystrokes:
+
+ <Enter> boot specified command line
+ <BackSpace> erase one character
+ <Ctrl-U> erase the whole line
+ <Ctrl-V> display the current Syslinux version
+ <Ctrl-W> erase one word
+ <Ctrl-X> force text mode
+ <Tab> list matching labels
+ <F1>..<F12> help screens (if configured)
+ <Ctrl-F><digit> equivalent to F1..F10
+ <Ctrl-C> interrupt boot in progress
+ <Esc> interrupt boot in progress
+ <Ctrl-N> display network information (PXELINUX only)
+
+
+=== WORKING DIRECTORY ===
+At start, the initial working directory for *SYSLINUX*/*ISOLINUX* will
+be the directory containing the initial configuration file. If no
+configuration file is found, *SYSLINUX* should default to the
+install-time working directory, however this is a known issue with some
+versions including 4.06.
+
+At start, the initial working directory for *PXELINUX* will be the
+parent directory of pxelinux.0 unless overridden with DHCP option 210.
+If no configuration file is found, *PXELINUX* will start a timer to
+reboot the system in an attempt to restart the boot process and resolve
+a possible transient issue.
+
+
+=== ALTERNATE FILENAMES ===
+For kernel-like file names given on the command line, *Syslinux* will
+attempt to append file name extensions to the specified file naem when
+the file is not found in the following order: .0[*PXELINUX* only],
+.bin[*ISOLINUX* only], .bs[*SYSLINUX* only], .bss[*SYSLINUX* only],
+.c32, .cbt, .com and .img[*ISOLINUX* 1.65-4.04 only].
+
+// Is this true of file names specified in a config? As of when?
+
+
+== AUTHOR ==
+This AsciiDoc derived document is a modified version of the original
+*SYSLINUX* documentation by {author} <{author-email}>. The conversion
+to an AsciiDoc was made by {editor1} <{editor1-email}>
diff --git a/txt/syslinux.cfg.txt b/txt/syslinux.cfg.txt
new file mode 100644
index 0000000..18b1681
--- /dev/null
+++ b/txt/syslinux.cfg.txt
@@ -0,0 +1,564 @@
+= syslinux.cfg(5) =
+:doctype: manpage
+:revdate: 2012-10-28
+:author: H. Peter Anvin
+:author-email: hpa at zytor.com
+:editor1: Gene Cumm
+:editor1-email: gene.cumm at gmail.com
+:editor1-revlast: 2012-10-28
+:nbsp8:
+:nbsp32: {nbsp8}{nbsp8}{nbsp8}{nbsp8}
+:data-uri:
+
+== NAME ==
+syslinux.cfg - *Syslinux* configuration file
+
+
+== DESCRIPTION ==
+Configuration for the boot behavior and user experience of *Syslinux*
+boot loaders, the format of display files and the boot prompt behavior.
+
+Blank lines are ignored.
+
+Note that the configuration file is not completely decoded. Syntax
+different from the one described above may still work correctly in this
+version of *Syslinux*, but may break in a future one.
+
+
+== LOCATION/NAME ==
+*SYSLINUX* (before 4.00) used the configuration filename of
+syslinux.cfg. *EXTLINUX* (merged into *SYSLINUX* as of 4.00) used the
+filename extlinux.conf. Both default to searching for the config file
+in the installed directory (containing ldlinux.sys/extlinux.sys). As of
+4.00, *SYSLINUX* will search for extlinux.conf then syslinux.cfg in each
+directory before falling back to the next directory.
+
+As of 3.35, *SYSLINUX* also searches /boot/syslinux, /syslinux and /.
+
+*ISOLINUX* (before 4.02) used the configuration filename of
+isolinux.cfg, searching /boot/isolinux (starting 2.00), then /isolinux
+and /. As of 4.02, *ISOLINUX* will search for isolinux.cfg then
+syslinux.cfg in /boot/isolinux before searching for the same files in
+/isolinux, /boot/syslinux, /syslinux, and /.
+
+
+== GLOBAL DIRECTIVES - MAIN ==
+*#* comment::
+A line comment. As of version 3.10, the space between the *#* and the
+comment is no longer required.
+
+*MENU* any string::
+(3.00+) A directive for the simple menu system, treated as a comment
+outside the menu. See menu.txt.
+
+*INCLUDE* 'filename'::
+Inserts the contents of another file at this point in the configuration
+file. Files can currently be nested up to 16 levels deep, but it is not
+guaranteed that more than 8 levels will be supported in the future.
+
+*DEFAULT* 'kernel' 'options...'::
+Sets the default command line. If *Syslinux* boots automatically, it
+will act just as if the entries after *DEFAULT* had been typed in at the
+'boot:' prompt. Multiple uses will result in an override.
++
+If no configuration file is present, or no *DEFAULT* or *UI* entry is
+present in the config file, an error message is displayed and the
+'boot:' prompt is shown (3.85+).
+
+*UI* 'module' 'options...'::
+Selects a specific user interface 'module' (typically menu.c32 or
+vesamenu.c32). The command-line interface treats this as a directive
+that overrides the *DEFAULT* directive to load this module instead at
+startup and for an empty command line and *PROMPT* directive to not
+prompt. Multiple uses will result in an override.
+
+*LABEL* 'mylabel'::
+Begin a new *LABEL* clause. If 'mylabel' is entered as the kernel to
+boot, *Syslinux* should instead boot "image" (specified by a directive
+from *KERNEL-LIKE DIRECTIVES*) with any specified *DUAL-PURPOSE
+DIRECTIVES* being used instead of the global instance.
++
+'mylabel' must be unique. Currently the first instance is used but may
+result in an error or undesired behavior. 'mylabel' ends at the first
+character that is not a non-white-space printable character and should
+be restricted to non-white-space typeable characters. Prior to version
+3.32, this would transformed to a DOS compatible format of 8.3 with a
+restricted character set. A *LABEL* clause must contain exactly 1 of
+the *KERNEL-LIKE DIRECTIVES* and may contain 1 each of the *LABEL-ONLY
+DIRECTIVES* or *DUAL-PURPOSE DIRECTIVES*.
++
+Within a *LABEL*, using multiple *KERNEL-LIKE DIRECTIVES* or reuse of
+*LABEL-ONLY DIRECTIVES* or *DUAL-PURPOSE DIRECTIVES* will result in an
+override. Otherwise, multiple instances of the same directive will
+result in the last being effective.
+
+
+== DUAL-PURPOSE DIRECTIVES ==
+Use of any of the *DUAL-PURPOSE DIRECTIVES* as *GLOBAL DIRECTIVES* is
+discouraged if there will be any non-Linux images loaded as *ALL* images
+will get these, including those manually entered at the 'boot:' prompt.
+
+*APPEND* 'options...'::
+Add one or more options to the kernel command line. These are added
+both for automatic and manual boots. The options are added at the very
+beginning of the kernel command line, usually permitting explicitly
+entered kernel options to override them. This is the equivalent of the
+LILO "append" option.
++
+Use of the parameter 'initrd=' supports multiple filenames separated by
+commas (ie 'initrd=initrd_file1,initrd_file2') within a single instance.
+This is mostly useful for initramfs, which can be composed of multiple
+separate cpio or cpio.gz archives.
++
+Note: all initrd files except the last one are zero-padded to a 4K page
+boundary. This should not affect initramfs.
++
+Note: Only the last effective 'initrd=' parameter is used for loading
+initrd files.
+
+*APPEND* -::
+Append nothing. *APPEND* with a single hyphen as argument in a *LABEL*
+section can be used to override a global *APPEND*.
+
+//[FIXME: Shorten subdefinitions]
+*IPAPPEND* 'flag_val'::
+(*PXELINUX* only) The *IPAPPEND* option is available only on *PXELINUX*.
+ The flag_val is an OR (sum) of the following integer options:
+
+ifndef::doctype-manpage[[horizontal]]
+*1*::: An option of the following format should be generated, based on
+the input from the DHCP/BOOTP or PXE boot server and added to the kernel
+command line(see note below):
++
+----
+ip=<client-ip>:<boot-server-ip>:<gw-ip>:<netmask>
+----
++
+NOTE: The use of option 1 is no substitute for running a DHCP client in
+the booted system and should instead only be used to seed the client for
+a request. Without regular renewals, the lease acquired by the PXE BIOS
+will expire, making the IP address available for reuse by the DHCP
+server.
++
+*2*::: An option of the following format should be generated, in
+dash-separated hexadecimal with leading hardware type (same as for the
+configuration file; see pxelinux.txt.) and added to the kernel command
+line, allowing an initrd program to determine from which interface the
+system booted:
++
+----
+BOOTIF=<hardware-address-of-boot-interface>
+----
++
+*4*::: An option of the following format should be generated, in lower
+case hexadecimal in the format normally used for UUIDs (same as for the
+configuration file; see pxelinux.txt.) and added to the kernel command
+line:
++
+----
+SYSUUID=<system uuid>
+----
+
+
+== KERNEL-LIKE DIRECTIVES ==
+// Alpha sort after KERNEL and LINUX
+*KERNEL* 'image'::
+Load a kernel-like file 'image' with automatic filetype detection based
+on file extension, listed under the non-auto-detecting directives,
+defaulting to *LINUX*.
+
+//[FIXME: Should "'image' as " be removed entirely or added to all?
+*LINUX* is used as an example]
+*LINUX* 'image'::
+Load 'image' as a Linux-like kernel. MEMDISK is an example of a
+non-Linux kernel loaded in a Linux-like fashion.
+
+*BOOT* 'image'::
+(*ISOLINUX* only: .bin; *SYSLINUX* only: .bs) Load a boot sector. .bin
+is a "CD boot sector" and .bs is a regular disk boot sector.
+
+*BSS* 'image'::
+(*SYSLINUX* only: .bss) Load a BSS image, a .bs image with the DOS
+superblock patched in.
+
+*COMBOOT* 'image'::
+(.com, .cbt) Load a *Syslinux* COMBOOT image. .com images may also be
+runnable from DOS while .cbt images are not. See also *comboot.txt*
+
+*COM32* 'image'::
+(.c32) Load a *Syslinux* COM32 (32-bit *COMBOOT*) image. See also
+*comboot.txt*
+
+*CONFIG* 'image'::
+Load a new configuration file. The configuration file is read, the
+working directory is changed (if specified via an *APPEND*), then the
+configuration file is parsed.
+
+*FDIMAGE* 'image'::
+(Removed as of 4.05, added 1.65; *ISOLINUX* only: .img) Load a disk
+image.
+
+*LOCALBOOT* 'type'::
+(*PXELINUX* 1.53+; *ISOLINUX* ??3.10+; *SYSLINUX* 3.70+)Attempt a
+different local boot method. The special value -1 causes the boot
+loader to report failure to the BIOS, which, on recent BIOSes, should
+mean that the next boot device in the boot sequence should be activated.
+ Values other than those documented may produce undesired results.
++
+On *PXELINUX*, "type" 0 means perform a normal boot. "type" 4 will
+perform a local boot with the Universal Network Driver Interface (UNDI)
+driver still resident in memory. Finally, "type" 5 will perform a local
+boot with the entire PXE stack, including the UNDI driver, still
+resident in memory. All other values are undefined. If you don't know
+what the UNDI or PXE stacks are, don't worry -- you don't want them,
+just specify 0.
++
+On *ISOLINUX*/*SYSLINUX*, the "type" specifies the local drive number to
+boot from; 0x00 is the primary floppy drive and 0x80 is the primary hard
+drive.
+
+*PXE* 'image'::
+(*PXELINUX* only: .0) Load a PXE NBP (Network Boot Program) image. The
+PXE protocol does not provide any means for specifiying or using a
+command line or initrd.
+
+
+== LABEL-ONLY DIRECTIVES ==
+*INITRD* 'initrd_file'::
+(3.71+) An initrd can be specified in a separate statement (INITRD)
+instead of as part of the *APPEND* statement; this functionally appends
+"initrd=initrd_file" to the kernel command line. Like 'initrd=', this
+also supports multiple comma separated file names (see *APPEND*).
+
+
+== GLOBAL DIRECTIVES - SECONDARY ==
+These are global directives that are of lesser importance, often
+affecting the user experience and not the boot process.
+
+*ALLOWOPTIONS* 'flag_val'::
+If 'flag_val' is 0, the user is not allowed to specify any arguments on
+the kernel command line. The only options recognized are those
+specified in an *APPEND*) statement. The default is 1.
+
+*IMPLICIT* 'flag_val'::
+If 'flag_val' is 0, do not load a kernel image unless it has been
+explicitly named in a *LABEL* statement. The default is 1.
+
+*TIMEOUT* 'timeout'::
+Indicates how long to wait at the 'boot:' prompt until booting
+automatically, in units of 1/10 s. The timeout is cancelled as soon as
+the user types anything on the keyboard, the assumption being that the
+user will complete the command line already begun. A timeout of zero
+(the default) will disable the timeout completely.
+
+*TOTALTIMEOUT* 'timeout'::
+Indicates how long to wait until booting automatically, in units of
+1/10 s. This timeout is *not* cancelled by user input, and can thus be
+used to deal with serial port glitches or "the user walked away" type
+situations. A timeout of zero will disable the timeout completely, this
+is also the default.
++
+Both *TIMEOUT* and *TOTALTIMEOUT* can be used together, for example:
++
+----
+# Wait 5 seconds unless the user types something, but
+# always boot after 15 minutes.
+TIMEOUT 50
+TOTALTIMEOUT 9000
+----
+
+*ONTIMEOUT* 'kernel options...'::
+Sets the command line invoked on a timeout. Normally this is the same
+thing as invoked by "DEFAULT". If this is specified, then "DEFAULT" is
+used only if the user presses <Enter> to boot.
+
+*ONERROR* 'kernel options...'::
+If a kernel image is not found (either due to it not existing, or
+because *IMPLICIT* is set), run the specified command. The faulty
+command line is appended to the specified options, so if the *ONERROR*
+directive reads as:
++
+----
+ONERROR xyzzy plugh
+----
++
+and the command line as entered by the user is:
++
+----
+foo bar baz
+----
++
+*Syslinux* will execute the following as if entered by the user:
++
+----
+xyzzy plugh foo bar baz
+----
+
+*SERIAL* 'port [[baudrate] flowcontrol]'::
+Enables a serial port to act as the console. "port" is a number (0 =
+/dev/ttyS0 = COM1, etc.) or an I/O port address (e.g. 0x3F8); if
+"baudrate" is omitted, the baud rate defaults to 9600 bps. The serial
+parameters are hardcoded to be 8 bits, no parity, 1 stop bit.
++
+"flowcontrol" is a combination of the following bits:
++
+....
+0x001 - Assert DTR
+0x002 - Assert RTS
+0x008 - Enable interrupts
+0x010 - Wait for CTS assertion
+0x020 - Wait for DSR assertion
+0x040 - Wait for RI assertion
+0x080 - Wait for DCD assertion
+0x100 - Ignore input unless CTS asserted
+0x200 - Ignore input unless DSR asserted
+0x400 - Ignore input unless RI asserted
+0x800 - Ignore input unless DCD asserted
+....
++
+All other bits are reserved.
++
+Typical values are:
++
+....
+ 0 - No flow control (default)
+0x303 - Null modem cable detect
+0x013 - RTS/CTS flow control
+0x813 - RTS/CTS flow control, modem input
+0x023 - DTR/DSR flow control
+0x083 - DTR/DCD flow control
+....
++
+For the *SERIAL* directive to be guaranteed to work properly, it should
+be the first directive in the configuration file.
++
+NOTE: "port" values from 0 to 3 means the first four serial ports
+detected by the BIOS. They may or may not correspond to the legacy port
+values 0x3F8, 0x2F8, 0x3E8, 0x2E8.
++
+Enabling interrupts (setting the 0x008 bit) may give better
+responsiveness without setting the *NOHALT* option, but could
+potentially cause problems with buggy BIOSes.
+
+*NOHALT* 'flag_val'::
+If 'flag_val' is 1, don't halt the processor while idle. Halting the
+processor while idle significantly reduces the power consumption, but
+can cause poor responsiveness to the serial console, especially when
+using scripts to drive the serial console, as opposed to human
+interaction.
+
+*CONSOLE* 'flag_val'::
+If 'flag_val' is 0, disable output to the normal video console. If
+'flag_val' is 1, enable output to the video console (this is the
+default.)
++
+Some BIOSes try to forward this to the serial console and sometimes make
+a total mess thereof, so this option lets you disable the video console
+on these systems.
+
+*FONT* 'filename'::
+Load a font in .psf format before displaying any output (except the
+copyright line, which is output as ldlinux.sys itself is loaded.)
+*Syslinux* only loads the font onto the video card; if the .psf file
+contains a Unicode table it is ignored. This only works on EGA and VGA
+cards; hopefully it should do nothing on others.
+
+*KBDMAP* 'keymap'::
+Install a simple keyboard map. The keyboard remapper used is *very*
+simplistic (it simply remaps the keycodes received from the BIOS, which
+means that only the key combinations relevant in the default layout --
+usually U.S. English -- can be mapped) but should at least help people
+with AZERTY keyboard layout and the locations of = and , (two special
+characters used heavily on the Linux kernel command line.)
++
+The included program keytab-lilo.pl from the LILO distribution can be
+used to create such keymaps. The file keytab-lilo.txt contains the
+documentation for this program.
+
+*DISPLAY* 'filename'::
+Displays the indicated file on the screen at boot time (before the boot:
+prompt, if displayed). Please see the section below on *DISPLAY* files.
++
+NOTE: If the file is missing, this option is simply ignored.
+
+*SAY* 'message'::
+Prints the message on the screen.
+
+*PROMPT* 'flag_val'::
+If 'flag_val' is 0, display the boot: prompt only if the Shift or Alt
+key is pressed, or Caps Lock or Scroll lock is set (this is the
+default). If 'flag_val' is 1, always display the boot: prompt.
+
+*NOESCAPE* 'flag_val'::
+If 'flag_val' is set to 1, ignore the Shift/Alt/Caps Lock/Scroll Lock
+escapes. Use this (together with PROMPT 0) to force the default boot
+alternative.
+
+*NOCOMPLETE* 'flag_val'::
+If flag_val is set to 1, the Tab key does not display labels at the
+boot: prompt.
+
+// ...etc...
+*F1* 'filename'::
+*F2* 'filename'::
+*F3* 'filename'::
+*F4* 'filename'::
+*F5* 'filename'::
+*F6* 'filename'::
+*F7* 'filename'::
+*F8* 'filename'::
+*F9* 'filename'::
+*F10* 'filename'::
+*F11* 'filename'::
+*F12* 'filename'::
+Displays the indicated file on the screen when a function key is pressed
+at the boot: prompt. This can be used to implement pre-boot online help
+(presumably for the kernel command line options.) Please see the
+section below on DISPLAY files.
++
+When using the serial console, press <Ctrl-F><digit> to get to the help
+screens, e.g. <Ctrl-F><2> to get to the F2 screen. For F10-F12, hit
+<Ctrl-F><A>, <Ctrl-F>B, <Ctrl-F>C. For compatibility with earlier
+versions, F10 can also be entered as <Ctrl-F>0.
+
+
+== DISPLAY FILE FORMAT ==
+DISPLAY and function-key help files are text files in either DOS or UNIX
+format (with or without <CR>). In addition, the following special codes
+are interpreted:
+
+//[FIXME]: #1 doesn't break; #2 as-is; #3 broken but not on right; #4
+identical to #3
+// horizontal extends the line's label, reducing the definition
+// tab or space to shift explanation ? align beginning or end?
+
+// ifndef::doctype-manpage[[horizontal]]
+*<FF>*:: {nbsp32} = <Ctrl-L> = ASCII 12 +
+Clear the screen, home the cursor. Note that the screen is filled with
+the current display color.
+
+*<FF>*::
+= <Ctrl-L> = ASCII 12; Clear the screen, home the cursor. Note that the
+screen is filled with the current display color.
+
+*<FF>*:: <FF> = <Ctrl-L> = ASCII 12
++
+Clear the screen, home the cursor. Note that the screen is filled with
+the current display color.
+
+*<FF>*::
+<FF> = <Ctrl-L> = ASCII 12 +
+Clear the screen, home the cursor. Note that the screen is filled with
+the current display color.
+
+*<SI>*'<bg><fg>':: <SI> = <Ctrl-O> = ASCII 15
++
+Set the display colors to the specified background and foreground
+colors, where <bg> and <fg> are the 2 hex digits representing 1 byte,
+corresponding to the standard PC display attributes:
++
+ 0 = black 8 = dark grey
+ 1 = dark blue 9 = bright blue
+ 2 = dark green a = bright green
+ 3 = dark cyan b = bright cyan
+ 4 = dark red c = bright red
+ 5 = dark purple d = bright purple
+ 6 = brown e = yellow
+ 7 = light grey f = white
++
+Picking a bright color (8-f) for the background results in the
+corresponding dark color (0-7), with the foreground flashing.
++
+Colors are not visible over the serial console.
+
+*<CAN>*'filename<newline>':: <CAN> = <Ctrl-X> = ASCII 24
++
+If a VGA display is present, enter graphics mode and display the graphic
+included in the specified file. The file format is an ad hoc format
+called LSS16; the included Perl program "ppmtolss16" can be used to
+produce these images. This Perl program also includes the file format
+specification.
++
+The image is displayed in 640x480 16-color mode. Once in graphics mode,
+the display attributes (set by <SI> code sequences) work slightly
+differently: the background color is ignored, and the foreground colors
+are the 16 colors specified in the image file. For that reason,
+ppmtolss16 allows you to specify that certain colors should be assigned
+to specific color indicies.
++
+Color indicies 0 and 7, in particular, should be chosen with care: 0 is
+the background color, and 7 is the color used for the text printed by
+*Syslinux* itself.
+
+*<EM>*:: <EM> = <Ctrl-Y> = ASCII 25 +
+If we are currently in graphics mode, return to text mode.
+
+*<DLE>*..*<ETB>*:: <Ctrl-P>..<Ctrl-W> = ASCII 16-23
++
+These codes can be used to select which modes to print a certain part of
+the message file in. Each of these control characters select a specific
+set of modes (text screen, graphics screen, serial port) for which the
+output is actually displayed:
++
+ Character Text Graph Serial
+ ------------------------------------------------------
+ <DLE> = <Ctrl-P> = ASCII 16 No No No
+ <DC1> = <Ctrl-Q> = ASCII 17 Yes No No
+ <DC2> = <Ctrl-R> = ASCII 18 No Yes No
+ <DC3> = <Ctrl-S> = ASCII 19 Yes Yes No
+ <DC4> = <Ctrl-T> = ASCII 20 No No Yes
+ <NAK> = <Ctrl-U> = ASCII 21 Yes No Yes
+ <SYN> = <Ctrl-V> = ASCII 22 No Yes Yes
+ <ETB> = <Ctrl-W> = ASCII 23 Yes Yes Yes
++
+For example, the following will actually print out which mode the
+console is in:
++
+ <DC1>Text mode<DC2>Graphics mode<DC4>Serial port<ETB>
+
+*<SUB>*:: <SUB> = <Ctrl-Z> = ASCII 26
++
+End of file (DOS convention).
+
+*<BEL>*:: <BEL> = <Ctrl-G> = ASCII 7 +
+Beep the speaker.
+
+
+== BOOT LOADER IDS USED ==
+The Linux boot protocol supports a "boot loader ID", a single byte where
+the upper nybble specifies a boot loader family (3 = *Syslinux*) and the
+lower nybble is version or, in the case of *Syslinux*, media:
+
+ 0x31 (49) = SYSLINUX
+ 0x32 (50) = PXELINUX
+ 0x33 (51) = ISOLINUX
+ 0x34 (52) = EXTLINUX
+
+In recent versions of Linux, this ID is available as
+/proc/sys/kernel/bootloader_type.
+
+
+== NOVICE PROTECTION ==
+*Syslinux* will attempt to detect booting on a machine with too little
+memory, which means the Linux boot sequence cannot complete. If so, a
+message is displayed and the boot sequence aborted. Holding down the
+Ctrl key while booting disables this feature.
+
+Any file that *Syslinux* uses can be marked hidden, system or readonly
+if so is convenient; *Syslinux* ignores all file attributes. The
+*SYSLINUX* installer automatically sets the readonly/hidden/system
+attributes on LDLINUX.SYS.
+
+
+== KNOWN BUGS ==
+include::com-bug.txt[]
+
+
+== BUG REPORTS ==
+include::com-rpt.txt[]
+
+
+== AUTHOR ==
+This AsciiDoc derived document is a modified version of the original
+*SYSLINUX* documentation by {author} <{author-email}>. The conversion
+to an AsciiDoc was made by {editor1} <{editor1-email}>
diff --git a/txt/syslinux.txt b/txt/syslinux.txt
new file mode 100644
index 0000000..23cad49
--- /dev/null
+++ b/txt/syslinux.txt
@@ -0,0 +1,217 @@
+= syslinux(1) =
+:doctype: manpage
+:revdate: 2012-10-28
+:author: H. Peter Anvin
+:author-email: hpa at zytor.com
+:editor1: Gene Cumm
+:editor1-email: gene.cumm at gmail.com
+:editor1-revlast: 2012-10-28
+
+
+== NAME ==
+syslinux - Install SYSLINUX to a file system
+
+
+== SYNOPSIS ==
+[verse]
+*syslinux* ['OPTIONS'] 'DEVICE'
+*extlinux* ['OPTIONS'] 'PATH'
+*syslinux* [-h | --help]
+*extlinux* [-h | --help]
+
+
+== DESCRIPTION ==
+Install *SYSLINUX* to the 'DEVICE'/'PATH', altering the boot sector and
+installing the 'ldlinux.sys' boot loader file. For the Linux installer
+extlinux, 'PATH' is the desired path for the control files on a mounted,
+supported file system and sets the install-time working directory. For
+all others, 'DEVICE' must specify a FAT12/FAT16/FAT32 file system. For
+the Linux installers syslinux and syslinux-mtools, 'DEVICE' should be an
+unmounted file system. For the DOS/Win32/Win64 installers, 'DEVICE'
+should be a drive like 'a:' (case insensitive).
+
+For versions ~4.00 and later, either -i/--install or -U/--update must be
+specified unless modifying the ADV of an existing install (options
+tagged with 'ADV') or requesting the help/usage or version info, .
+
+If, during boot, the Shift or Alt keys are held down, or the Caps or
+Scroll locks are set, *Syslinux* will display a *lilo*(8) -style "boot:"
+prompt. The user can then type a kernel file name followed by any kernel
+parameters. The *Syslinux* bootloader does not need to know about the
+kernel or config files in advance.
+
+*Syslinux* supports the loading of initial ramdisks (initrd) and the
+bzImage kernel format.
+
+Please note, the ldlinux.sys boot loader file is flagged as immutable
+(where applicable) and is modified after copying in to help ensure
+boot-time integrity. File systems with a sufficiently large boot loader
+reserved area, like btrfs, will have ldlinux.sys installed there rather
+than as a normal file.
+
+
+== OPTIONS ==
+// "See"/"See also" notes should reference long options.
+=== Standalone options ===
+*-i*, *--install*::
+(~4.00+) Install SYSLINUX, regardless of an existing install.
+
+*-U*, *--update*::
+(~4.00+) Update an existing SYSLINUX/EXTLINUX install. If no Syslinux
+boot loader is present, return an error.
+
+*-h*, *--help*::
+Display help/usage information.
+
+*-v*, *--version*::
+Display version information and exit immediately.
+
+=== Regular Options ===
+// Sorted generally by short argument
+*-a*, *--active*::
+(DOS/Win32/Win64 ONLY) Mark the install target file system's partition
+active.
+
+*-d*, *--directory* 'subdirectory'::
+(Not necessary for extlinux as it is implied by 'PATH') Install the
+*SYSLINUX* control files in a subdirectory with the specified name
+(relative to the root directory on the device).
+
+*--device* 'DEVICE'::
+(extlinux ONLY; 4.06+) Force use of a specific block device (experts
+only).
+
+*-f*, *--force*::
+Force install even if it appears unsafe. Before 4.00, -f was used for
+--offset in the Linux installers.
+
+*-H*, *--heads* 'head-count'::
+Override the detected number of heads for the geometry. See also
+*--sector*.
+
+*-m*, *--mbr*:
+(DOS/Win32/Win64 ONLY) Install the regular Syslinux MBR code to the MBR.
+
+*-M*, *--menu-save*::
+(4.00+; ADV) Set the label to select as default on the next boot.
+
+*-o*, *--once* 'command'::
+(ADV) Declare a boot command to be tried on the first boot only. The
+use of *-o* for the Linux installers syslinux or syslinux-mtools has
+been deprecated as of ~4.00 and is no longer valid as of ~4.02.
+
+*-O*, *--clear-once*::
+Clear the boot-once command. See also *--once*.
+
+*-r*, *--raid*::
+(ADV) RAID mode. If boot fails, tell the BIOS to boot the next device
+in the boot sequence (usually the next hard disk) instead of stopping
+with an error message. This is useful for RAID-1 booting.
+
+*--reset-adv*::
+(ADV) Reset auxilliary data vector.
+
+*-S*, *--sectors* 'sector-count'::
+Override the detected number of sectors for the geometry. See also
+*--head*.
+
+*-s*, *--stupid*::
+Install a "safe, slow and stupid" version of *SYSLINUX*. This version
+may work on some very buggy BIOSes on which *SYSLINUX* would otherwise
+fail. If you find a machine on which the -s option is required to make
+it boot reliably, please send as much info about your machine as you
+can, and include the failure mode.
+
+*-t*, *--offset* 'offset'::
+(Linux syslinux/syslinux-mtools ONLY) Indicates that the filesystem is
+at an offset from the base of the device or file.
+
+*-z*, *--zipdrive*
+Assume zipdrive geometry ('--heads 64 --sectors 32'). See also *--head*
+and *--sector*.
+
+
+== EXAMPLES ==
+=== Booting DOS ===
+For booting DOS and other similar operating systems, there is an easy
+and generally reliable solution to substitute in SYSLINUX as the primary
+boot loader.
+
+- Make a DOS-bootable disk; The following are possible commands:
+
+ format a: /s
+ sys a:
+
+- Copy the DOS boot sector off using Linux or copybs.com:
+
+ dd if=/dev/fd0 of=dos.bss bs=512 count=1
+ copybs a: a:dos.bss
+
+- Install SYSLINUX using one of:
+
+ syslinux a:
+ syslinux /dev/fd0 (before 4.00)
+ syslinux -i /dev/fd0 (4.00+)
+
+- For Linux, mount the disk and copy the dos.bss to the disk:
+
+ mount -t msdos /dev/fd0 /mnt
+ cp dos.bss /mnt
+
+- Copy a Linux kernel image and initrd payload files:
+*Linux:*::
+ cp vmlinux /mnt
+ cp initrd.gz /mnt
+*DOS/Windows:*::
+ copy vmlinux a:
+ copy initrd.gz a:
+
+- For Linux, umount the disk (if applicable):
+
+ umount /mnt
+
+=== MBR ===
+In order to boot from a hard disk (or hard disk-like device) in BIOS
+mode, an appropriate MBR boot block must also be installed in the MBR
+(first sector or 512 bytes of the disk), occupying at most 440 bytes.
+
+*DOS/Windows:*::
+If using FDISK, FDISK or a similar application must also be used to mark
+the partition as active.
++
+ fdisk /mbr
+ OR
+ syslinux -ma c:
+
+*Linux:*::
++
+ dd bs=440 count=1 conv=notrunc if=mbr/mbr.bin of=/dev/sda
++
+For altmbr.bin, an easy way to overwrite the MBR boot block and specify
+the partion number is:
++
+ printf '\1' | cat altmbr.bin - | dd bs=440 count=1 iflag=fullblock conv=notrunc of=/dev/sda
++
+Note: using 'cat' for writing the MBR can under some circumstances cause
+data loss or overwritting. For this reason, using 'dd' is recommended
+for all situations.
+
+//[FIXME]: any clean way to handle the above long command for manpage?
+
+
+== SEE ALSO ==
+*syslinux.cfg*(5), *syslinux-cli*(1), *lilo*(8), *keytab-lilo.pl*(8),
+*fdisk*(8), *mkfs*(8), *superformat*(1).
+
+
+== AUTHOR ==
+This AsciiDoc derived document is a modified version of the original
+*SYSLINUX* documentation by {author} <{author-email}>. The conversion to
+a manpage was made by Arthur Korn <arthur at korn.ch>. The conversion to
+an AsciiDoc was made by {editor1} <{editor1-email}>
+
+
+== COPYRIGHT ==
+Copyright \(C) 1994-2012 {author}. Free use of this software is granted
+under the terms of the GNU General Public License (GPL), version 2
+(GPLv2) (or, at your option, any later version).
More information about the Syslinux-commits
mailing list