From 01fea662b22875b8f94aa2ab5f836acf7b0378f1 Mon Sep 17 00:00:00 2001

From: Cyrill Gorcunov <gorcunov@gmail.com>

Date: Sun, 17 Feb 2013 22:50:19 +0400

Subject: [PATCH] Generate manpages from asciidoc format

---

 Makefile.in  |  14 +-

 configure.in |   4 +-

 nasm.1       | 535 -----------------------------------------------------------

 nasm.txt     | 303 +++++++++++++++++++++++++++++++++

 ndisasm.1    | 129 --------------

 ndisasm.txt  |  94 +++++++++++

 6 files changed, 410 insertions(+), 669 deletions(-)

 delete mode 100644 nasm.1

 create mode 100644 nasm.txt

 delete mode 100644 ndisasm.1

 create mode 100644 ndisasm.txt

diff --git a/Makefile.in b/Makefile.in

index d7b4e22..46b7c00 100644

--- a/Makefile.in

+++ b/Makefile.in

@@ -31,6 +31,8 @@ INSTALL_PROGRAM	= @INSTALL_PROGRAM@

 INSTALL_DATA	= @INSTALL_DATA@

 NROFF		= @NROFF@

+ASCIIDOC	= @ASCIIDOC@

+XMLTO		= @XMLTO@

 MKDIR		= mkdir

 RM		= rm

@@ -47,7 +49,7 @@ ifeq ($(TRACE),1)

 	CFLAGS += -DNASM_TRACE

 endif

-.SUFFIXES: .c .i .s .$(O) .1 .man

+.SUFFIXES: .c .i .s .$(O) .1 .txt .xml

 .PHONY: all doc rdf install clean distclean cleaner spotless install_rdf test

 .PHONY: install_doc everything install_everything strip perlreq dist tags TAGS

@@ -61,8 +63,12 @@ endif

 .c.i:

 	$(CC) -E $(ALL_CFLAGS) -o $@ $<

-.1.man:

-	$(NROFF) -man $< > $@

+.txt.xml:

+	$(ASCIIDOC) -b docbook -d manpage -o $@ $<

+

+.xml.1:

+	$(XMLTO) man --skip-validation $< 2>/dev/null

+

 #-- Begin File Lists --#

 NASM =	nasm.$(O) nasmlib.$(O) ver.$(O) \

@@ -88,7 +94,7 @@ NDISASM = ndisasm.$(O) disasm.$(O) sync.$(O) nasmlib.$(O) ver.$(O) \

 	insnsd.$(O) insnsb.$(O) insnsn.$(O) regs.$(O) regdis.$(O)

 #-- End File Lists --#

-all: nasm$(X) ndisasm$(X) nasm.man ndisasm.man rdf

+all: nasm$(X) ndisasm$(X) nasm.1 ndisasm.1 rdf

 nasm$(X): $(NASM) $(XOBJS)

 	$(CC) $(LDFLAGS) -o nasm$(X) $(NASM) $(XOBJS) $(LIBS)

diff --git a/configure.in b/configure.in

index 8c6a429..da2154d 100644

--- a/configure.in

+++ b/configure.in

@@ -67,7 +67,9 @@ PA_ADD_CFLAGS([-std=c99])

 PA_ADD_CFLAGS([-pedantic])

 dnl Look for programs...

-AC_CHECK_PROGS(NROFF,    nroff,    echo)

+AC_CHECK_PROGS(NROFF,    nroff,    false)

+AC_CHECK_PROGS(ASCIIDOC, asciidoc, false)

+AC_CHECK_PROGS(XMLTO,    xmlto,    false)

 AC_CHECK_PROGS(ACRODIST, acrodist, false)

 AC_CHECK_PROGS(PS2PDF,   ps2pdf,   false)

 AC_CHECK_PROGS(PSTOPDF,  pstopdf,  false)

diff --git a/nasm.1 b/nasm.1

deleted file mode 100644

index bca0cd5..0000000

--- a/nasm.1

+++ /dev/null

@@ -1,535 +0,0 @@

-.TH NASM 1 "The Netwide Assembler Project"

-.SH NAME

-nasm \- the Netwide Assembler, a portable 80x86 assembler

-.SH SYNOPSIS

-.B nasm

-[

-.B \-@

-response file

-] [

-.B \-f

-format

-] [

-.B \-o

-outfile

-] [

-.B \-l

-listfile

-] [

-.IR options ...

-] filename

-.br

-.B nasm \-h

-.br

-.B nasm \-v

-.SH DESCRIPTION

-The

-.B nasm

-command assembles the file

-.I filename

-and directs output to the file

-.I outfile

-if specified. If

-.I outfile

-is not specified,

-.B nasm

-will derive a default output file name from the name of its input

-file, usually by appending `.o' or `.obj', or by removing all

-extensions for a raw binary file. Failing that, the output file name

-will be `nasm.out'.

-.SS OPTIONS

-.TP

-.BI \-@ " filename"

-Causes

-.B nasm

-to process options from 

-.I filename

-as if they were included on the command line.

-.TP

-.B \-a

-Causes

-.B nasm

-to assemble the given input file without first applying the macro

-preprocessor.

-.TP

-.BI \-D " macro[=value]"

-Pre-defines a single-line macro.

-.TP

-.BI \-d " macro[=value]"

-Same as the

-.B \-D

-option.

-.TP

-.B \-e

-Causes

-.B nasm

-to preprocess the given input file, and write the output to

-.I stdout

-(or the specified output file name), and not actually assemble

-anything.

-.TP

-.BI \-f " format"

-Specifies the output file format. To see a list of valid output

-formats, use the

-.B -hf

-option.

-.TP

-.B \-g

-Causes

-.B nasm

-to generate debug information in selected format

-.TP

-.B \-h

-Causes

-.B nasm

-to exit immediately, after giving a summary of its invocation

-options.

-.TP

-.B \-hf

-Same as

-.B -h

-, but also lists all valid output formats.

-.TP

-.BI \-I " directory"

-Adds a directory to the search path for include files. The directory

-specification must include the trailing slash, as it will be

-directly prepended to the name of the include file.

-.TP

-.BI \-i " directory"

-Same as the

-.B \-I

-option.

-.TP

-.BI \-l " listfile"

-Causes an assembly listing to be directed to the given file, in

-which the original source is displayed on the right hand side (plus

-the source for included files and the expansions of multi-line

-macros) and the generated code is shown in hex on the left.

-.TP

-.B \-M

-Causes

-.B nasm

-to output Makefile-style dependencies to stdout; normal output is

-suppressed.

-.TP

-.BI \-MG " file"

-Same as

-.B \-M

-but assumes that missing Makefile dependecies are generated and added

-to dependency list without a prefix.

-.TP

-.BI \-MF " file"

-Output Makefile-style dependencies to the specified file.

-.TP

-.BI \-MD " file"

-Same as a combination of

-.B \-M

-and

-.B \-MF

-options.

-.TP

-.BI \-MT " file"

-Override the default name of the dependency target

-dependency target name. This is normally the same

-as the output filename, specified by the

-.B \-o

-option.

-.TP

-.BI \-MQ " file"

-The same as

-.B \-MT

-except it tries to quote characters that have special

-meaning in Makefile syntax. This is not foolproof,

-as not all characters with special meaning are quotable

-in Make.

-.TP

-.BI \-MP

-Emit phony target

-.TP

-.BI \-O " number"

-Optimize branch offsets.

-.ti

-.B \-O0

-:No optimization

-.ti

-.B \-O1

-:Minimal optimization

-.ti

-.B \-Ox

-:Multipass optimization (default)

-.TP

-.BI \-o " outfile"

-Specifies a precise name for the output file, overriding

-.BR nasm 's

-default means of determining it.

-.TP

-.BI \-P " file"

-Specifies a file to be pre-included, before the main source file

-starts to be processed.

-.TP

-.BI \-p " file"

-Same as the

-.B \-P

-option.

-.TP

-.BI \-r

-Causes

-.B nasm

-to exit immediately, after displaying its version number.

-.I (obsolete)

-.TP

-.B \-s

-Causes

-.B nasm

-to send its error messages and/or help text to

-.I stdout

-instead of

-.IR stderr .

-.TP

-.B \-t

-Causes

-.B nasm

-to assemble in SciTech TASM compatible mode

-.TP

-.BI \-U " macro"

-Undefines a single-line macro.

-.TP

-.BI \-u " macro"

-Same as the

-.B \-U

-option.

-.TP

-.BI \-v

-Causes

-.B nasm

-to exit immediately, after displaying its version number.

-.TP

-.BI \-w [+-]foo

-Causes

-.B nasm

-to enable or disable certain classes of warning messages, for

-example

-.B \-w+orphan-labels

-or

-.B \-w-macro-params

-.TP

-.BI \-X " format"

-specifies error reporting format (gnu or vc).

-.TP

-.BI \-Z " filename"

-Causes

-.B nasm

-to redirect error messages to

-.IR filename .

-This option exists to support operating systems on which stderr is not

-easily redirected.

-.TP

-.BI \-\-prefix

-.TP

-.BI \-\-postfix

-Prepend or append (respectively) the given argument to all

-global or extern variables.

-.PP

-.RE

-.SS SYNTAX

-This man page does not fully describe the syntax of

-.BR nasm 's

-assembly language, but does give a summary of the differences from

-other assemblers.

-.PP

-.I Registers

-have no leading `%' sign, unlike

-.BR gas ,

-and floating-point stack registers are referred to as

-.IR st0 ,

-.IR st1 ,

-and so on.

-.PP

-.I Floating-point instructions

-may use either the single-operand form or the double. A

-.I TO

-keyword is provided; thus, one could either write

-.PP

-.ti +15n

-fadd st0,st1

-.br

-.ti +15n

-fadd st1,st0

-.PP

-or one could use the alternative single-operand forms

-.PP

-.ti +15n

-fadd st1

-.br

-.ti +15n

-fadd to st1

-.PP

-.I Uninitialised storage

-is reserved using the

-.IR RESB ,

-.IR RESW ,

-.IR RESD ,

-.IR RESQ ,

-.I REST

-and

-.I RESO

-pseudo-opcodes, each taking one parameter which gives the number of

-bytes, words, doublewords, quadwords or ten-byte words to reserve.

-.PP

-.I Repetition

-of data items is not done by the

-.I DUP

-keyword as seen in DOS assemblers, but by the use of the

-.I TIMES

-prefix, like this:

-.PP

-.ti +6n

-.ta 9n

-message:	times 3 db 'abc'

-.br

-.ti +15n

-times 64-$+message db 0

-.PP

-which defines the string `abcabcabc', followed by the right number

-of zero bytes to make the total length up to 64 bytes.

-.PP

-.I Symbol references

-are always understood to be immediate (i.e. the address of the

-symbol), unless square brackets are used, in which case the contents

-of the memory location are used. Thus:

-.PP

-.ti +15n

-mov ax,wordvar

-.PP

-loads AX with the address of the variable `wordvar', whereas

-.PP

-.ti +15n

-mov ax,[wordvar]

-.br

-.ti +15n

-mov ax,[wordvar+1]

-.br

-.ti +15n

-mov ax,[es:wordvar+bx]

-.PP

-all refer to the

-.I contents

-of memory locations. The syntaxes

-.PP

-.ti +15n

-mov ax,es:wordvar[bx]

-.br

-.ti +15n

-es mov ax,wordvar[1]

-.PP

-are not legal at all, although the use of a segment register name as

-an instruction prefix is valid, and can be used with instructions

-such as

-.I LODSB

-which can't be overridden any other way.

-.PP

-.I Constants

-may be expressed numerically in most formats: a trailing H, Q or B

-denotes hex, octal or binary respectively, and a leading `0x' or `$'

-denotes hex as well. Leading zeros are not treated specially at all.

-Character constants may be enclosed in single or double quotes;

-there is no escape character. The ordering is little-endian

-(reversed), so that the character constant

-.I 'abcd'

-denotes 0x64636261 and not 0x61626364.

-.PP

-.I Local labels

-begin with a period, and their `locality' is granted by the

-assembler prepending the name of the previous non-local symbol. Thus

-declaring a label `.loop' after a label `label' has actually defined

-a symbol called `label.loop'.

-.SS DIRECTIVES

-.I SECTION name

-or

-.I SEGMENT name

-causes

-.B nasm

-to direct all following code to the named section. Section names

-vary with output file format, although most formats support the

-names

-.IR .text ,

-.I .data

-and

-.IR .bss .

-(The exception is the

-.I obj

-format, in which all segments are user-definable.)

-.PP

-.I ABSOLUTE address

-causes

-.B nasm

-to position its notional assembly point at an absolute address: so

-no code or data may be generated, but you can use

-.IR RESB ,

-.I RESW

-and

-.I RESD

-to move the assembly point further on, and you can define labels. So

-this directive may be used to define data structures. When you have

-finished doing absolute assembly, you must issue another

-.I SECTION

-directive to return to normal assembly.

-.PP

-.I BITS 16,

-.I BITS 32

-or

-.I BITS 64

-switches the default processor mode for which

-.B nasm

-is generating code: it is equivalent to

-.I USE16

-or

-.I USE32

-in DOS assemblers.

-.PP

-.I EXTERN symbol

-and

-.I GLOBAL symbol

-import and export symbol definitions, respectively, from and to

-other modules. Note that the

-.I GLOBAL

-directive must appear before the definition of the symbol it refers

-to.

-.PP

-.I STRUC strucname

-and

-.IR ENDSTRUC ,

-when used to bracket a number of

-.IR RESB ,

-.I RESW

-or similar instructions, define a data structure. In addition to

-defining the offsets of the structure members, the construct also

-defines a symbol for the size of the structure, which is simply the

-structure name with

-.I _size

-tacked on to the end.

-.SS FORMAT-SPECIFIC DIRECTIVES

-.I ORG address

-is used by the

-.I bin

-flat-form binary output format, and specifies the address at which

-the output code will eventually be loaded.

-.PP

-.I GROUP grpname seg1 seg2...

-is used by the

-.I obj

-(Microsoft 16-bit) output format, and defines segment groups. This

-format also uses

-.IR UPPERCASE ,

-which directs that all segment, group and symbol names output to the

-object file should be in uppercase. Note that the actual assembly is

-still case sensitive.

-.PP

-.I LIBRARY libname

-is used by the

-.I rdf

-output format, and causes a dependency record to be written to the

-output file which indicates that the program requires a certain

-library in order to run.

-.SS MACRO PREPROCESSOR

-Single-line macros are defined using the

-.I %define

-or

-.I %idefine

-commands, in a similar fashion to the C preprocessor. They can be

-overloaded with respect to number of parameters, although defining a

-macro with no parameters prevents the definition of any macro with

-the same name taking parameters, and vice versa.

-.I %define

-defines macros whose names match case-sensitively, whereas

-.I %idefine

-defines case-insensitive macros.

-.PP

-Multi-line macros are defined using

-.I %macro

-and

-.I %imacro

-(the distinction is the same as that between

-.I %define

-and

-.IR %idefine ),

-whose syntax is as follows:

-.PP

-.ti +6n

-%macro

-.I name

-.IR minprm [- maxprm "][+][.nolist] [" defaults ]

-.br

-.ti +15n

-<some lines of macro expansion text>

-.br

-.ti +6n

-%endmacro

-.PP

-Again, these macros may be overloaded. The trailing plus sign

-indicates that any parameters after the last one get subsumed, with

-their separating commas, into the last parameter. The

-.I defaults

-part can be used to specify defaults for unspecified macro

-parameters after

-.IR minparam .

-.I %endm

-is a valid synonym for

-.IR %endmacro .

-.PP

-To refer to the macro parameters within a macro expansion, you use

-.IR %1 ,

-.I %2

-and so on. You can also enforce that a macro parameter should

-contain a condition code by using

-.IR %+1 ,

-and you can invert the condition code by using

-.IR %-1 .

-You can also define a label specific to a macro invocation by

-prefixing it with a double % sign.

-.PP

-Files can be included using the

-.I %include

-directive, which works like C.

-.PP

-The preprocessor has a `context stack', which may be used by one

-macro to store information that a later one will retrieve. You can

-push a context on the stack using

-.IR %push ,

-remove one using

-.IR %pop ,

-and change the name of the top context (without disturbing any

-associated definitions) using

-.IR %repl .

-Labels and

-.I %define

-macros specific to the top context may be defined by prefixing their

-names with %$, and things specific to the next context down with

-%$$, and so on.

-.PP

-Conditional assembly is done by means of

-.IR %ifdef ,

-.IR %ifndef ,

-.I %else

-and

-.I %endif

-as in C. (Except that

-.I %ifdef

-can accept several putative macro names, and will evaluate TRUE if

-any of them is defined.) In addition, the directives

-.I %ifctx

-and

-.I %ifnctx

-can be used to condition on the name of the top context on the

-context stack. The obvious set of `else-if' directives,

-.IR %elifdef ,

-.IR %elifndef ,

-.IR %elifctx

-and

-.IR %elifnctx

-are also supported.

-.SH BUGS

-Please report bugs through the bug tracker function at http://nasm.sourceforge.org.

-.SH SEE ALSO

-.BR as "(" 1 "),"

-.BR ld "(" 1 ")."

diff --git a/nasm.txt b/nasm.txt

new file mode 100644

index 0000000..55f9a05

--- /dev/null

+++ b/nasm.txt

@@ -0,0 +1,303 @@

+nasm(1)

+=======

+:doctype:	manpage

+:man source:	NASM

+:man manual:	The Netwide Assembler Project

+

+NAME

+----

+nasm - the Netwide Assembler, a portable 80x86 assembler

+

+SYNOPSIS

+--------

+*nasm* [*-@* response file] [*-f* format] [*-o* outfile] [*-l* listfile] ['options'...] filename

+

+DESCRIPTION

+-----------

+The *nasm* command assembles the file 'filename' and directs output to the file

+'outfile' if specified. If 'outfile' is not specified, *nasm* will derive a default

+output file name from the name of its input file, usually by appending `.o' or

+`.obj', or by removing all extensions for a raw binary file. Failing that, the

+output file name will be `nasm.out'.

+

+OPTIONS

+-------

+*-@* 'filename'::

+	Causes *nasm* to process options from filename as if they were included on

+	the command line.

+

+*-a*::

+	Causes *nasm* to assemble the given input file without first applying the

+	macro preprocessor.

+

+*-D*|*-d* 'macro[=value]'::

+	Pre-defines a single-line macro.

+

+*-E*|*-e*::

+	Causes *nasm* to preprocess the given input file, and write the output to

+	'stdout' (or the specified output file name), and not actually assemble

+	anything.

+

+*-f* 'format'::

+	Specifies the output file format. To see a list of valid output formats,

+	use the *-hf* option.

+

+*-F* 'format'::

+	Specifies the debug information format. To see a list of valid output

+	formats, use the *-y* option (for example *-felf -y*).

+

+*-g*::

+	Causes *nasm* to generate debug information in selected format.

+

+*-h*::

+	Causes *nasm* to exit immediately, after giving a summary of its

+	invocation options.

+

+*-hf*::

+	Same as *-h* , but also lists all valid output formats.

+

+*-I*|*-i* 'directory'::

+	Adds a directory to the search path for include files. The directory

+	specification must include the trailing slash, as it will be directly

+	prepended to the name of the include file.

+

+*-l* 'listfile'::

+	Causes an assembly listing to be directed to the given file, in which

+	the original source is displayed on the right hand side (plus the source

+	for included files and the expansions of multi-line macros) and the

+	generated code is shown in hex on the left.

+

+*-M*::

+	Causes *nasm* to output Makefile-style dependencies to stdout; normal

+	output is suppressed.

+

+*-MG* 'file'::

+	Same as *-M* but assumes that missing Makefile dependecies are generated

+	and added to dependency list without a prefix.

+

+*-MF* 'file'::

+	Output Makefile-style dependencies to the specified file.

+

+*-MD* 'file'::

+	Same as a combination of *-M* and *-MF* options.

+

+*-MT* 'file'::

+	Override the default name of the dependency target dependency target name.

+	This is normally the same as the output filename, specified by

+	the *-o* option.

+

+*-MQ* 'file'::

+	The same as *-MT* except it tries to quote characters that have special

+	meaning in Makefile syntax. This is not foolproof, as not all characters

+	with special meaning are quotable in Make.

+