add info manual

Signed-off-by: Mattias Andrée <maandree@operamail.com>

1 files changed, 218 insertions, 0 deletions

diff --git a/doc/info/librarian.texinfo b/doc/info/librarian.texinfo
new file mode 100644
index 0000000..906d002
--- /dev/null
+++ b/doc/info/librarian.texinfo
@@ -0,0 +1,218 @@
+\input texinfo   @c -*-texinfo-*-
+
+@c %**start of header
+@setfilename librarian.info
+@settitle librarian
+@afourpaper
+@documentencoding UTF-8
+@documentlanguage en
+@finalout
+@c %**end of header
+
+
+@dircategory Development
+@direntry
+* librarian: (librarian).           Library to compiler flags resolver
+@end direntry
+
+
+@copying
+Copyright @copyright{} 2015 Mattias Andrée
+
+@quotation
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.3 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
+Texts. A copy of the license is included in the section entitled
+``GNU Free Documentation License''.
+@end quotation
+@end copying
+
+@ifnottex
+@node Top
+@top librarian -- Library to compiler flags resolver
+@insertcopying
+@end ifnottex
+
+@titlepage
+@title librarian
+@subtitle Library to compiler flags resolver
+@author by Mattias Andrée (maandree)
+
+@page
+@vskip 0pt plus 1filll
+@insertcopying
+@page
+@end titlepage
+
+@contents
+
+
+
+@menu
+* Overview::                        Brief overview of @command{librarian}.
+* Invoking::                        Invocation of @command{librarian}.
+* Files::                           @command{librarian} files.
+* GNU Free Documentation License::  Copying and sharing this manual.
+@end menu
+
+
+
+@node Overview
+@chapter Overview
+
+@command{librarian} is used to print flags required
+when compiling or linking, and want to use library
+that requires non-trival flags@footnote{Just @option{-l}
+and the library name sans `lib'}.
+
+
+
+@node Invoking
+@chapter Invoking
+
+Synopsis:
+@example
+librarian [OPTION]... [--] [VARIABLE]... [LIBRARY]...
+@end example
+
+@command{librarian} shall output the flags, required
+by the selected libraries, that are listed under the
+selected variables.
+
+@code{LIBRARY} can either be the name of the required
+library, the name of the required library and a version
+of said library, or the name of the required library
+and an accepted version range of said library. If the
+same library name is used more than once, the versions
+and version ranges are unioned. Recognised formats are:
+@table @code
+@item NAME
+Any version of the library @code{NAME} will do.
+@item NAME=VERSION
+Only version @code{VERSION} of the library @code{NAME}
+is acceptable. (Multiple version can be used by
+specifying more than once.)
+@item NAME<=MAX
+Any versions up to and including @code{MAX} of the
+library @code{NAME} will do.
+@item NAME<MAX
+Any versions up to but excluding @code{MAX} of the
+library @code{NAME} will do.
+@item NAME>=MIN
+At least version @code{MIN} of the library @code{NAME}
+is required.
+@item NAME>MIN
+A greater version than version @code{MIN} of the
+library @code{NAME} is required.
+@item NAME>=MIN<=MAX
+Combines, by intersection, @code{NAME>=MIN} and
+@code{NAME<=MAX}.
+@item NAME>=MIN<MAX
+Combines, by intersection, @code{NAME>=MIN} and
+@code{NAME<MAX}.
+@item NAME>MIN<=MAX
+Combines, by intersection, @code{NAME>MIN} and
+@code{NAME<=MAX}.
+@item NAME>MIN<MAX
+Combines, by intersection, @code{NAME>MIN} and
+@code{NAME<MAX}.
+@end table
+
+The are not predefined values for @code{VARIABLE},
+but the standardised ones are:
+@table @code
+@item CFLAGS
+Flags required by the compiler to compile the if
+the library @code{LIBRARY} is used. The library
+is a C library.
+@item CPPFLAGS
+Flags required by the C preprocessor to compile
+the if the library @code{LIBRARY} is used.
+@item LDFLAGS
+Flags required by the linker to link the program
+when the library @code{LIBRARY} is used.
+@item CXXFLAGS
+Flags required by the compiler to compile the if
+the library @code{LIBRARY} is used. The library
+is a C++ library.
+@item deps
+Libraries the library @code{LIBRARY} is dependent
+on. Flags from these libraries should not appear
+in the other variables unless the library
+@code{LIBRARY} requires them directly.
+@end table
+
+If @code{VARIABLE} is omitted, the process will
+exit with the value @code{0} if all listed libraries,
+@code{LIBRARY}, are available, and otherwise exit
+with the value @code{2}.
+
+@command{librarian} recognises the following
+options:
+@table @option
+@item -d
+Add output for dependencies too. Should be used
+for @code{LDFLAGS} when linking statically.
+@item -l
+Print the location of the files specified by
+@code{LIBRARY}. Cannot be combined with @option{-d}.
+@item -o
+Prefer older libraries, when multiple versions
+are available. This is useful if you are afraid
+of new software.
+@end table
+
+@command{librarian} is affected by the following
+environment variables:
+@table @env
+@item LIBRARIAN_PATH
+Colon-separated list of directories to search
+for @command{librarian} files.
+@end table
+
+@command{librarian} will exit with one of the
+following exit statuses:
+@table @code
+@item 0
+The program was successful.
+@item 1
+An error occurred.
+@item 2
+A library was not found.
+@item 3
+Usage error.
+@end table
+
+
+
+@node Files
+@chapter Files
+
+@command{librarian} files should be stored in
+@file{PREFIX/share/librarian/}. Its filename should
+be the name of the library, followed by an 
+(equals-sign) and the version number. For example
+@file{/usr/share/librarian/libmy=1.0}
+
+Empty lines and lines starting with a @code{#} (she)
+in a @command{librarian} files are ignored. Other
+lines should begin with a variable name and be
+followed by the required flags relevant to that
+variable. For the variable deps, @command{libraries}
+that the library requires should be listed in the
+same format the @code{LIBRARY} argument uses,
+in @ref{Invoking}.
+
+All variables should be in upper case unless they are
+reserved. In the latter case, the are lower cased.
+
+
+
+@node GNU Free Documentation License
+@appendix GNU Free Documentation License
+@include fdl.texinfo
+
+@bye
+