;;; user.skb -- The Skribilo user manual. -*- coding: iso-8859-1 -*- ;;; ;;; Copyright 2005, 2006, 2007, 2008, 2009, 2012, 2020 Ludovic Courtès ;;; Copyright 2001, 2002, 2003, 2004 Manuel Serrano ;;; ;;; ;;; This file is part of Skribilo. ;;; ;;; Skribilo 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 3 of the License, or ;;; (at your option) any later version. ;;; ;;; Skribilo 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 Skribilo. If not, see . ;*---------------------------------------------------------------------*/ ;* The Skribilo documentation style */ ;*---------------------------------------------------------------------*/ (use-modules (skribilo documentation env) (skribilo documentation manual) (skribilo documentation api)) ;*---------------------------------------------------------------------*/ ;* Packages */ ;*---------------------------------------------------------------------*/ (use-modules (skribilo package eq) (skribilo package pie) (skribilo package slide) (skribilo package web-book2) (skribilo source lisp) (skribilo source xml) (skribilo source c)) ;*---------------------------------------------------------------------*/ ;* Internals */ ;*---------------------------------------------------------------------*/ (use-modules (skribilo ast) (skribilo reader) (skribilo engine) (skribilo writer) (skribilo output) (skribilo evaluator) (skribilo config) (skribilo index) (skribilo lib) ;; for `skribe-warning' (skribilo utils syntax)) ;; `set-correct-file-encoding!' ;*---------------------------------------------------------------------*/ ;* SRFIs */ ;*---------------------------------------------------------------------*/ (use-modules (srfi srfi-19)) (if %have-ploticus? (set! %ploticus-program %ploticus-path)) ;; Modules needed, e.g., to get the output of "skribilo-config --help". (use-modules (ice-9 popen) (ice-9 rdelim) (ice-9 pretty-print) (srfi srfi-13)) ;*---------------------------------------------------------------------*/ ;* HTML custom */ ;*---------------------------------------------------------------------*/ ;; since we load slides (for documenting it), we have to use a ;; correct title width (let ((he (find-engine 'html))) (engine-custom-set! he 'body-width 100.)) ;*---------------------------------------------------------------------*/ ;* Example bibliography */ ;*---------------------------------------------------------------------*/ (bibliography "src/bib1.sbib") ;*---------------------------------------------------------------------*/ ;* The document */ ;*---------------------------------------------------------------------*/ (document :title "Skribilo User Manual" :keywords '("Skribilo" "Skribe" "User Manual" "text processing" "HTML" "LaTeX" "Lout" "PostScript" "PDF") :info-dir-category "Document authoring" :info-dir-entry "Authoring documents with Skribilo." :env '((example-counter 0) (example-env ())) :author (list (author :name "Érick Gallesio" :affiliation "Université de Nice - Sophia-Antipolis" :email (mailto "eg@essi.fr")) (author :name "Manuel Serrano" :affiliation "Inria" :email (mailto *serrano-mail*)) (author :name "Ludovic Courtès" :email (mailto *courtes-mail*))) (resolve (lambda (n e env) ;; The Lout engine uses the `book' style, where we can't have ;; text outside of chapters. (and (not (engine-format? "lout" e)) (p :class "welcome" [Welcome to the User Manual for Skribilo version ,(skribilo-version)! If you are new to Skribilo, please read the ,(ref :ident "intro" :text [introduction]) first.])))) (if (engine-format? "html") ;; Produce a complete table of contents on the main HTML page. (toc :chapter #t :section #t :subsection #t)) ;;; Introduction (chapter :title "Introduction" :ident "intro" :number #f :toc #t :file #f (p [Skribilo is a document production toolkit and a programming language designed for implementing electronic documents,(footnote [To be more precise, the programming language itself is that of ,(ref :text [Skribe] :url *skribe-url*), the project Skribilo is based on.]). It is mainly designed for the writing of technical documents such as the documentation of computer programs. With Skribilo these documents can be rendered using various tools and technologies. For instance, a Skribilo document can be ,(emph "compiled") to an HTML file that suits Web browser, it can be compiled to a TeX file in order to produce a high-quality printed document, and so on.]) (p [This manual documents Skribilo version ,(skribilo-version). Since it is based on Skribe's user manual, you might stumble upon documentation bits that are obsolete or inaccurate in the context of Skribilo, although work is being done to fix it.]) ;; FIXME (section :title "Who May Use Skribilo?" :number #f (p [Anyone needing to design web pages, PostScript/PDF files or Info documents can use Skribilo. In particular, there is ,(emph "no need") for programming skills in order to use Skribilo. Skribilo can be used as any text description languages such as ,(ref :text [LaTeX] :url "http://latex-project.org/"), ,(ref :text [Lout] :url "http://lout.sf.net/") or HTML.])) (section :title "Why Use Skribilo?" :number #f (p [There are three main reasons for using Skribilo:] (itemize (item [ It is easier to type in Skribilo texts than other text description formats. The need for ,(emph "meta keywords"), that is, words used to describe the structure of the text and not the text itself, is very limited.]) (item [ Skribilo is highly skilled for computing texts. It is very common that one needs to automatically produce parts of the text. This can be very simple such as, for instance, the need to include inside a text, the date of the last update or the number of the last revision. Sometimes it may be more complex. For instance, one may be willing to embed inside a text the result of a complex arithmetic computation. Or even, you may want to include some statistics about that text, such as, the number of words, paragraphs, sections, and so on. Skribilo makes these sort of text manipulation easy whereas other systems rely on the use of text preprocessors.]) (item [ The same source file can be compiled to various output formats such as HTML, PostScript, Info pages, etc.])))) (section :title "More on Skribilo" :number #f (p [Skribilo is based on ,(ref :text [Skribe] :url *skribe-url*), which was designed and implemented by Manuel Serrano and Érick Gallesio. Although it departs from it on some aspects, it shares the overall design and philosophy. Érick and Manuel described the main design decisions behind Skribe in a paper published in the 2005 Journal of Functional Programming (JFP) entitled ,(ref :url "http://www-sop.inria.fr/mimosa/Manuel.Serrano/publi/jfp05/article.html" :text (it [Skribe: A Functional Authoring Language])). Although parts of the paper are slightly outdated, it gives a very good idea of Skribilo's innards, and notably contains a description of the 3 stages of documentation ``evaluation''.]))) ;;; toc (if (engine-format? "latex") (toc :chapter #t :section #t :subsection #t)) ;;; Getting started (include "start.skb") ;;; Syntax (include "syntax.skb") ;;; Skribilo Markup Library (include "markup.skb") ;;; Hyperlinks and references (include "links.skb") ;;; Indexes (include "index.skb") ;;; Bibliography (include "bib.skb") ;;; Computer programs (include "prgm.skb") ;;; Equations (include "eq.skb") ;;; Pie charts (if %have-ploticus? (include "pie.skb")) ;;; Slides (include "slide.skb") ;;; Packages (include "package.skb") ;;; Standard Library (include "lib.skb") ;;; Engines (include "engine.skb") ;;; Compiler (include "compiler.skb") ;;; skribilo-config (include "skribilo-config.skb") ;;; Emacs (include "emacs.skb") ;;; List of examples (include "examples.skb") ;;; table of contents (resolve (lambda (n e env) (cond ((and (not (engine-format? "latex" e)) (not (engine-format? "lout" e)) (not (engine-format? "info" e))) (list (and (not (engine-format? "html" e)) (chapter :title "Table of Contents" (toc :chapter #t :section #t :subsection #t))) (chapter :title "Index" :number #f :ident "Index" (mark "global index") (the-index :column (if (engine-format? "latex") 2 3) *markup-index* *custom-index* *function-index* *package-index* (default-index))))) ((and (not (engine-format? "lout" e)) (not (engine-format? "info" e))) (chapter :title "Index" :ident "Index" (mark "global index") (the-index :column (if (engine-format? "latex") 2 3) *markup-index* *custom-index* *function-index* *package-index* (default-index)))) (else ;; FIXME: We don't have a clean `the-index' in Lout. (skribe-warning 0 "index not available for this engine" e) #f))))) ;; Local Variables: ;; comment-start: ";" ;; comment-end: "" ;; ispell-local-dictionary: "american" ;; End: