Учебник по Проекту Документирования FreeBSD для новых участников

lang

*
doc/
doc/
lang.encoding/
sgml-mode
<book>
<article>

.profile
.cshrc
INCLUDE
IGNORE
<h1>
<h2>
<hn>

<blockquote>
<ul>
<ol>
<dl>
<pre>
<table>
rowspan
colspan
rowspan
colspan




<tt>
<big>


<a
href="...">
<a
name="...">
<book>
<bookinfo>
<article>
<articleinfo>
<para>
<blockquote>
<warning>
<itemizedlist>
<orderedlist>
<procedure>
<programlisting>
<co>
<calloutlist>
<informaltable>
frame="none"
<screen>
<prompt>
<userinput>
<emphasis>
<filename>
<filename>
role
<devicename>
<hostid>
<username>
<maketarget>
<makevar>
<literal>
<replaceable>
<errorname>
id в главах и разделах
<anchor>
<xref>
<link>
<ulink>
<book>
<article>
root
.login
ls -a
You have mail.

% su
Password:

root
rm filename
$HOME
textproc/docproj
# cd /usr/ports/textproc/docproj
# make JADETEX=no install

doc
checkout
doc/share
doc/en_US.ISO8859-1/share
% cvs checkout doc/share
% cvs checkout doc/en_US.ISO8859-1/share

% cvs checkout doc

articles
% cvs checkout doc/en_US.ISO8859-1/articles

vpn-w2k
% cd doc/en_US.ISO8859-1/articles
% cp -R committers-guide vpn-w2k

doc/en_US.ISO8859-1/books/faq
% cvs checkout doc/en_US.ISO8859-1/books/faq

.sgml
lint
% make lint

html
html-split
txt
ps
pdf
rtf
doc/share/mk/doc.docbook.mk
html
% make FORMATS=html

html
txt
% make FORMATS=html
% make FORMATS=txt

% make FORMATS="html txt"

textproc/docproj
textproc/docproj
# make JADETEX=yes install

# make JADETEX=no install

textproc/docproj-jadetex
textproc/docproj-nojadetex
JADETEX
textproc/docproj
textproc/sp
textproc/jade
www/tidy
www/links
graphics/peps
textproc/html
textproc/docbook
textproc/iso8879
textproc/dsssl-docbook-modular
print/jadetex
print/teTeX
print/jadetex/pkg-message
editors/emacs
editors/emacs
/tmp/foo
% rm /tmp/foo

<para>Для удаления <filename>/tmp/foo</filename>, воспользуйтесь командой
  &man.rm.1;.</para>

<screen>&prompt.user; <userinput>rm /tmp/foo</userinput></screen>

element-name
<element-name>
</element-name>
p
Это параграф. Он начинается с начальной
 метки для элемента 'p' и заканчивается конечной меткой для элемента
 'p'.

Это другой параграф. Но он гораздо короче.

hr
<p>Это параграф.</p>

<hr>

Это другой параграф. Горизонтальная линия отделяет его от предыдущего
 параграфа.

<em>
<p>Это простой <em>параграф</em>, в котором
  некоторые <em>слова</em> были <em>выделены</em>.</p>

<
p
>
название-атрибута="значение
атрибута"
<p>
align
align
left
center
right
justify
left
<p align="left">Включение атрибута
  выравнивания для этого параграфа было излишним, так как по умолчанию
  используется выравнивание по левой границе.</p>

<p align="center">Это может появиться по центру.</p>

left
justify
"
<p align='right'>Я справа!</p>

textproc/docproj
textproc/docproj
SGML_CATALOG_FILES
.profile
SGML_ROOT=/usr/local/share/sgml    
SGML_CATALOG_FILES=${SGML_ROOT}/jade/catalog
SGML_CATALOG_FILES=${SGML_ROOT}/iso8879/catalog:$SGML_CATALOG_FILES
SGML_CATALOG_FILES=${SGML_ROOT}/html/catalog:$SGML_CATALOG_FILES
SGML_CATALOG_FILES=${SGML_ROOT}/docbook/4.1/catalog:$SGML_CATALOG_FILES
SGML_CATALOG_FILES=/usr/doc/share/sgml/catalog:$SGML_CATALOG_FILES
SGML_CATALOG_FILES=/usr/doc/en_US.ISO8859-1/share/sgml/catalog:$SGML_CATALOG_FILES
export SGML_CATALOG_FILES

.cshrc
setenv SGML_ROOT /usr/local/share/sgml
setenv SGML_CATALOG_FILES ${SGML_ROOT}/jade/catalog
setenv SGML_CATALOG_FILES ${SGML_ROOT}/iso8879/catalog:$SGML_CATALOG_FILES
setenv SGML_CATALOG_FILES ${SGML_ROOT}/html/catalog:$SGML_CATALOG_FILES
setenv SGML_CATALOG_FILES ${SGML_ROOT}/docbook/4.1/catalog:$SGML_CATALOG_FILES
setenv SGML_CATALOG_FILES /usr/doc/share/sgml/catalog:$SGML_CATALOG_FILES
setenv SGML_CATALOG_FILES /usr/doc/en_US.ISO8859-1/share/sgml/catalog:$SGML_CATALOG_FILES

example.sgml
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">

<html>
  <head>    
    <title>Пример файла HTML</title>
  </head>

  <body>    
    <p>Это параграф, содержащий некоторый текст.</p>

    <p>В этом параграфе содержится дополнительный текст.</p>

    <p align="right">Этот параграф может быть выровнен по правому краю.</p>
  </body>
</html>

textproc/docproj
nsgmls
nsgmls
nsgmls
nsgmls
nsgmls
% nsgmls -s example.sgml

nsgmls
<title>
</title>
% nsgmls -s example.sgml
nsgmls:example.sgml:5:4:E: character data is not allowed here
nsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished

nsgmls
nsgmls
I
W
E
X
nsgmls -sv
nsgmls:I: SP version
"1.3"
<title>
<head>
<title>
<head>
<title>
nsgmls
title
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN">

<!
DOCTYPE
html
PUBLIC "-//W3C//DTD HTML 4.0//EN"
PUBLIC
>
"Владелец//Ключевое слово Описание//Язык"

Владелец
"ISO 8879:1986//ENTITIES Greek Symbols//EN"
ISO 8879:1986
-//Владелец
+//Владелец
+
-
-
+
-//FreeBSD
Ключевое слово
DTD
ELEMENT
ENTITIES
TEXT
DTD
ELEMENT
TEXT
Описание
Язык
EN
catalog
catalog
PUBLIC "-//W3C//DTD HTML 4.0//EN"             "4.0/strict.dtd"

strict.dtd
4.0
catalog
/usr/local/share/sgml/html/catalog
textproc/docproj
SGML_CATALOG_FILES
catalog
SGML_CATALOG_FILES
/usr/local/share/sgml/docbook/4.1/catalog
/usr/local/share/sgml/html/catalog
/usr/local/share/sgml/iso8879/catalog
/usr/local/share/sgml/jade/catalog
<!DOCTYPE html SYSTEM "/path/to/file.dtd">

SYSTEM
SYSTEM
<! ...
>
--
<!-- Тестовый комментарий -->

<!-- Это находится внутри комментария -->

<!-- Это еще один комментарий    -->

<!-- Это один из способов
     создания многострочных комментариев -->

<!-- Это другой способ   --
  -- создания многострочных комментариев -->

<!--
-->
<!-- Это находится внутри комментария --

     ЭТО ВНЕ КОММЕНТАРИЯ!

  -- снова внутри комментария -->

<!ЭТО ВНЕ КОММЕНТАРИЯ>

<!--------------- Это очень плохая идея --------------->

<!--===================================================-->

example.sgml
nsgmls
example.sgml
nsgmls
&имя-сущности;
current.version
<para>Текущей версией нашего продукта является
  &current.version;.</para>

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
<!ENTITY current.version    "3.0-RELEASE">
<!ENTITY last.version       "2.2.7-RELEASE">
]>

&имени-сущности;
%имя-сущности;
%
ENTITY
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
<!ENTITY % param.some "some">
<!ENTITY % param.text "text">
<!ENTITY % param.new  "%param.some more %param.text">

<!-- %param.new теперь содержит "some more text" -->
]>

example.sgml
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" [
<!ENTITY version "1.1">
]>  

<html>
  <head>    
    <title>Пример файла HTML</title>
  </head>

  <!-- Вы можете также поместить здесь комментарии -->

  <body>    
    <p>Этот параграф содержит некоторый текст.</p>

    <p>Этот параграф содержит некоторый дополнительный текст.</p>

    <p align="right">Этот параграф может быть выравнен по правому краю.</p>

    <p>Текущая версия этого документа: &version;</p>
  </body>
</html>

nsgmls
example.sgml
example.html
&version;
sgmlnorm
% sgmlnorm example.sgml > example.html

example.html
sgmlnorm
% sgmlnorm -d example.sgml > example.html

chapter1.sgml
chapter2.sgml
book.sgml
SYSTEM
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
<!ENTITY chapter.1 SYSTEM "chapter1.sgml">
<!ENTITY chapter.2 SYSTEM "chapter2.sgml">
<!ENTITY chapter.3 SYSTEM "chapter3.sgml">
<!-- И так далее -->
]>

<html>
  <!-- Используем сущности для подгрузки глав -->

  &chapter.1;
  &chapter.2;
  &chapter.3;
</html>

chapter1.sgml
chapter2.sgml
chapters.ent
<!ENTITY chapter.1 SYSTEM "chapter1.sgml">
<!ENTITY chapter.2 SYSTEM "chapter2.sgml">
<!ENTITY chapter.3 SYSTEM "chapter3.sgml">

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
<!-- Определение параметризованной сущности для подгрузки сущностей общего
     назначения -->
<!ENTITY % chapters SYSTEM "chapters.ent">

<!-- А теперь используем параметризованную сущность для загрузки их в файл -->
%chapters;
]>

<html>
  &chapter.1;
  &chapter.2;
  &chapter.3;
</html>

para1.sgml
para2.sgml
para3.sgml
<p>Это первый параграф.</p>

example.sgml
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
<!ENTITY version "1.1">
<!ENTITY para1 SYSTEM "para1.sgml">
<!ENTITY para2 SYSTEM "para2.sgml">
<!ENTITY para3 SYSTEM "para3.sgml">
]>

<html>
  <head>
    <title>Пример файла HTML</title>
  </head>

  <body>
    <p>Текущая версия этого документа: &version;</p>

    &para1;
    &para2;
    &para3;
  </body>
</html>

example.html
example.sgml
% sgmlnorm -d example.sgml > example.html

example.html
paran.sgml
example.html
example.sgml
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
<!ENTITY % entities SYSTEM "entities.sgml"> %entities;
]>

<html>
  <head>
    <title>Пример файла HTML</title>
  </head>

  <body>
    <p>Текущая версия этого документа: &version;</p>

    &para1;
    &para2;
    &para3;
  </body>
</html>

entities.sgml
<!ENTITY version "1.1">
<!ENTITY para1 SYSTEM "para1.sgml">
<!ENTITY para2 SYSTEM "para2.sgml">
<!ENTITY para3 SYSTEM "para3.sgml">

example.html
example.sgml
% sgmlnorm -d example.sgml > example.html

example.html
paran.sgml
example.html
<![ KEYWORD [
  Содержимое отмеченного раздела
]]>

<!
KEYWORD
>
CDATA
RCDATA
CDATA
RCDATA
CDATA
RCDATA
CDATA
RCDATA
CDATA
CDATA
<para>Вот пример того, как вы должны включать
  некоторый текст, содержащий множество символов &lt; и &amp;.  Текст
  в примере является фрагментом HTML.  Окружающие текст (<para> и
  <programlisting>) из DocBook.</para>

<programlisting>
  <![ CDATA [  
    <p>Это пример, показывающий вам некоторые элементы HTML.  Так как угловые
      скобки используются так часто, то проще всего указать, что весь пример
      является разделом, помеченным как CDATA, чем использовать имена сущностей
      для левых и правых угловых скобок по всему тексту.</p>

    <ul>
      <li>Это элемент списка</li>
      <li>Это второй элемент списка</li>
      <li>Это третий элемент списка</li>
    </ul>

    <p>Это конец примера.</p>
  ]]>
</programlisting>

INCLUDE
IGNORE
INCLUDE
IGNORE
INCLUDE
IGNORE
<![ INCLUDE [
 Этот текст будет обработан и включен.
]]>

<![ IGNORE [
 Этот текст не будет обработан и включен.
]]>

INCLUDE
IGNORE
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
<!ENTITY % electronic.copy "INCLUDE">    
]]>

...

<![ %electronic.copy [
 Этот текст должен появиться только в электронной
 версии документа.
]]>

<!ENTITY % electronic.copy "IGNORE">

%electronic.copy
section.sgml
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
<!ENTITY % text.output "INCLUDE">
]>

<html>
  <head>
    <title>Пример использования помеченных разделов</title>
  </head>

  <body> 
    <p>Этот параграф <![ CDATA [содержит много символов <
      (< < < < <), так что проще заключить его в раздел,
      помеченный как CDATA ]]></p>

    <![ IGNORE [
    <p>Этот параграф определенно не будет включен в выходной
      документ.</p>
    ]]>

    <![ %text.output [
    <p>Этот параграф может быть включен в выходной документ, а может там и
      не оказаться.</p>

    <p>Его появление контролируется параметризованной сущностью
      %text.output.</p>  
    ]]>
  </body>
</html>

text.output
INCLUDE
IGNORE
textproc/html
textproc/docproj
PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"

<head>
<body>
<html>
<html>
  <head>
      <title>Заголовок документа</title>
  </head>

  <body>

    ...

  </body>
</html>

<h1>
<h2>
<h6>
<h1>
<h2>
<h1>First section</h1>

<!-- Здесь помещается введение документа -->

<h2>Это заголовок первого раздела</h2>

<!-- Здесь размещается содержимое первого раздела -->

<h3>Это заголовок первого подраздела</h3>

<!-- Здесь размещается содержимое первого подраздела -->

<h2>Это заголовок второго раздела</h2>

<!-- Здесь размещается содержимое второго раздела -->

<h1>
<h2>
<hn>
<hn>
<h1>Первый раздел</h1>

<!-- Введение документа -->

<h3>Подраздел</h3>

<!-- Это плохо, пропущен <h2> -->

Это параграф. Он может содержать
практически любой другой элемент.

<blockquote>
<p>Короткий отрывок из Конституции США:</p>

<blockquote>We the People of the United States, in Order to form
  a more perfect Union, establish Justice, insure domestic
  Tranquility, provide for the common defence, promote the general
  Welfare, and secure the Blessings of Liberty to ourselves and our
  Posterity, do ordain and establish this Constitution for the
  United States of America.</blockquote>

<ol>
<ul>
<dl>
<li>
<p>
<dt>
<dd>
<ul>
<ol>
<p>Неупорядоченный список.  Элементам
списка должны предшествовать маркеры.</p>

<ul>
  <li>Первый элемент</li>

  <li>Второй элемент</li>

  <li>Третий элемент</li>
</ul>

Упорядоченный список, с элементами, состоящими из нескольких параграфов.
 Каждый элемент (замечание: но не каждый параграф) будет пронумерован.

<ol>
 <li>Это первый элемент. В нем только один параграф.</li>

  <li><p>Это первый параграф второго элемента.</p>

    <p>Это второй параграф второго элемента.</p></li>

  <li><p>Это первый и единственный параграф третьего элемента списка.</p></li>
</ol>

<dl>
<dl>
  <dt>Термин 1</dt>

  <dd><p>Параграф 1 определения 1.</p>

    <p>Параграф 2 определения 1.</p></dd>

  <dt>Термин 2</dt>

  <dd><p>Параграф 1 определения 2.</p></dd>

  <dt>Термин 3</dt>

  <dd>Параграф 1 определения 3.  Заметьте, что элемент &lt;p&gt;
    в случае единственного параграфа не нужен.</dd>
</dl>

<pre>
<pre>
<pre>
<pre>  From: nik@FreeBSD.org
  To: freebsd-doc@FreeBSD.org
  Subject: New documentation available

  There's a new copy of my primer for contributers to the FreeBSD
  Documentation Project available at

    <URL:http://people.FreeBSD.org/~nik/primer/index.html>

  Comments appreciated.

  N</pre>

<table>
<tr>
<td>
<p>
<table>
<p>Это простая таблица 2x2.</p>

<table>
  <tr>
    <td>Верхняя левая ячейка</td>

    <td>Верхняя правая ячейка</td>
  </tr>

  <tr>
    <td>Нижняя левая ячейка</td>

    <td>Нижняя правая ячейка</td>
  </tr>
</table>

rowspan
colspan
rowspan
<p>Одна высокая тонкая ячейка слева,
  две низкие ячейки за ней справа.</p>

<table>
  <tr>
    <td rowspan="2">Длинная и высокая</td>
  </tr>

  <tr>
    <td>Верхняя ячейка</td>

    <td>Нижняя ячейка</td>
  </tr>
</table>

colspan
<p>Одна длинная ячейка сверху, две
  короткие ячейки под ней.</p>

<table>
  <tr>
    <td colspan="2">Верхняя ячейка</td>
  </tr>

  <tr>
    <td>Нижняя левая ячейка</td>

    <td>Нижняя правая ячейка</td>
  </tr>
</table>

rowspan
colspan
На сетке 3x3 верхний левый блок является
 набором клеток 2x2, объединенных в одну ячейку.
 Остальные клетки нормальные.

<table>
  <tr>
    <td colspan="2" rowspan="2">Верхняя левая большая ячейка</td>

    <td>Верхняя правая клетка</td>
  </tr>

  <tr>
    <!-- Из-за того, что большая ячейка слева объединяется в
     эту строку, первый <td> появится справа -->

    <td>Средняя правая ячейка</td>
  </tr>

  <tr>
    <td>Нижняя левая ячейка</td>

    <td>Нижняя средняя ячейка</td>

    <td>Нижняя правая ячейка</td>
  </tr>
</table>

<em>
<strong>
<em>
<strong>
<em>
<strong>
<em>
<strong>
<p><em>Этот текст</em> выделен, а
  <strong>этот текст</strong> выделен сильно.</p>

<b>
<i>
<b>
<i>
<p><b>Этот текст</b> выводится жирным, а
  <i>этот текст</i> выводится наклонным шрифтами.</p>

<tt>
<tt>
<p>Этот документ первоначально создал
  Ник Клэйтон (Nik Clayton), которому можно написать по электронной почте
на адрес <tt>nik@FreeBSD.org</tt>.</p>

<big>
<small>
<big><big>этот текст гораздо
крупнее</big></big>
<font>
size
+1
-1
<big>
<small>
<font>
size
3
<big>
<small>
<font>
<p>Этот текст <small>немного меньше</small>.  А
  этот текст <big>немножко больше</big>.</p>

Этот текст несколько меньше. А
 этот текст немного крупнее</font.

Этот текст немного мельче. А
 этот текст немного крупнее.

<a>
href
<a href="...">
<p>Дополнительная информация находится на
  <a href="http://www.FreeBSD.org/">веб-сайте FreeBSD</a>.</p>

<a>
name
href
<a name="...">
<p><a name="para1">На</a> этот параграф
  можно сослаться из других мест
  по имени <tt>para1</tt>.</p>

#
para1
foo.html
<p>Дополнительная информация может быть
  найдена в <a href="foo.html#para1">первом абзаце</a> из
  <tt>foo.html</tt>.</p>

#
para1
<p>Дополнительная информация может быть
  найдена в <a href="#para1">первом абзаце</a> этого
  документа.</p>

Формально
неформально
textproc/docbook
textproc/docproj

Пользователь	Приглашение
Обычный пользователь	`%`
`root`	`#`

Значение	Примеры
Названия команд, имена файлов и каталогов. Выдача на экран.	Отредактируйте ваш файл `.login`. Используйте команду `ls -a` для выдачи списка всех файлов. You have mail.
То, что набираете вы, когда это отличается от экранной выдачи компьютером.	`%` `su` Password:
Ссылки на страницы справочной системы.	Воспользуйтесь командой su(1) для смены имени пользователя.
Имена пользователей и групп	Только `root` может это делать.
Выделение	Вы должны это сделать.
Переменные параметры командной строки; заменяйте их реальными названиями или значениями.	Для удаления файла наберите `rm filename`
Переменные окружения	`$HOME` является вашим домашним каталогом.

Столбец	Значение
1	Название программы, обнаружившей ошибку. Это всегда будет `nsgmls`.
2	Имя файла, содержащего ошибку.
3	Номер строки, в которой появилась ошибка.
4	Номер колонки, в которой появилась ошибка.
5	Однобуквенный код, обозначающий природу сообщения. `I` обозначает информационное сообщение, `W` для предупреждений и `E` для ошибок [a] и `X` для перекрестных ссылок. Как видите, это сообщения об ошибках.
6	Текст диагностического сообщения.
Примечания: a. Пятая колонка выводится не всегда. `nsgmls -sv` выдает `nsgmls:I: SP version "1.3"` (это зависит от установленной версии). Как вы можете видеть, это информационное сообщение.

The FreeBSD Documentation Project

Используемые сокращения

Глава 1. Обзор

Глава 2. Инструменты

Глава 3. Учебник SGML

Глава 4. Разметка SGML