Chapter 4 SGML Маркиране

Table of Contents
4.1 HTML
4.2 DocBook

Тази глава описва двата езика за маркиране, които ще срещнете когато работите по Проекта за Документация на FreeBSD. Всяка от секциите описва език за маркиране и детайли за маркирането, което ще използвате или което вече ползвате.

Езиците за маркиране съдържат голям брой елементи и понякога е объркващо, кой елемент да се използва в определена ситуация. Тази секция разглежда елементите от които най-вероятно ще имате нужда и дава примери как да ги използвате.

Това не е изчерпателен списък, тъй като това просто би повторило документацията на всеки от езиците. Целта на тази секция е да разгледа елементите които биха ви били от полза. Ако имате въпрос относно как е най-добре да се маркира определена част от съдържание, моля изпратете го в FreeBSD documentation project mailing list .

Inline срещу block: От тук нататък, когато описваме елементи inline означава, че елемента може да бъде поставен във блоков елемент и не предизвиква край на линията. block елемент ще предизвиква край на линията когато се срещне.

4.1 HTML

HTML, HyperText Markup Language, е избраният език за World Wide Web. Повече информация може да се намери на <URL:http://www.w3.org/>.

HTML се използва за маркиране на уеб сайта на FreeBSD. В общи линии не се използва за маркиране на друга документация тъй като DocBook предлага доста по-богат набор елементи. Следователно, ще попадате на HTML страници само ако пишете за уеб сайта.

HTML преминава през версии 1, 2, 3.0, 3.2 и последната 4.0 (достъпна в strict и loose варианти).

HTML DTD (типови дефиниции на документ) са достъпни от порт колекцията чрез textproc/html порт. Те се инсталират автоматично като част от textproc/docproj порт.

4.1.1 Формален Публичен Идентификатор - Formal Public Identifier (FPI)

Има няколко HTML FPI, в зависимост от версията (също известна като ниво) на HTML която декларирате като версията към която вашите документи се придържат.

По-голямата част от HTML документи в уеб сайта на FreeBSD се придържат към loose (освободена) версия на HTML 4.0.

PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"

4.1.2 Секционни елементи

Всеки HTML документ обикновенно е разделен на две секции. Първата секция, наречена head съдържа мета-информация за документа, като заглавието му, името на автора и т.н. Втората секция body съдържа това което ще бъде показано на потребителя.

Тези секции се означават с <head> и <body>. Те са елементи на най-високото <html> ниво.

Example 4-1. Стандартна структура на HTML документ

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

  <body>

    ...

  </body>
</html>

4.1.3 Блокови елементи

4.1.3.1 Заглавия

HTML позволява да обозначавате заглавия до шест различни нива.

Най-голямото и най-важно е <h1>, след това <h2> до <h6>.

Съдържанието на елемента е текста на заглавието.

Example 4-2. <h1>, <h2> и т.н.

Използване:

<h1>First section</h1>

<!-- Document introduction goes here -->

<h2>This is the heading for the first section</h2>

<!-- Content for the first section goes here -->

<h3>This is the heading for the first sub-section</h3>

<!-- Content for the first sub-section goes here -->

<h2>This is the heading for the second section</h2>

<!-- Content for the second section goes here -->

В основни линии, една HTML страница трябва да има един заглавен елемент от първо ниво (<h1>). Той може да съдържа много заглавия от второ ниво (<h2>), което от своя страна съдържа много заглавия от трето ниво. Всеки <hn> елемент (освен първия) трябва да има същия брой без един, предхождащи го елементи. Пропускане на ниво трябва да се избягва.

Example 4-3. Лошо подреждане на <hn> елементи

Използване:

<h1>First section</h1>

<!-- Document introduction -->

<h3>Sub-section</h3>

<!-- This is bad, <h2> has been left out -->

4.1.3.2 Параграфи

HTML поддържа единичен елемент параграф, <p>.

Example 4-4. <p>

Използване:

<p>This is a paragraph.  It can contain just about any
  other element.</p>

4.1.3.3 Блокови цитати

Блоково цитиране е разширено цитиране от друг документ, което не трябва да се появява в текущият параграф.

Example 4-5. <блоков цитат>

Използване:

<p>A small excerpt from the US Constitution:</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>

4.1.3.4 Списъци

Можете да представите три типа списъци - подреден, неподреден и дефиниция.

Обикновенно всеки ред в подреден списък ще бъде номериран, докато при неподредените списъци ще бъде с начална точка. Дефиниционните списъци се състоят от две части. Първата е термина, който се дефинира, а втората е самата дефиниция.

Подредените списъци се дефинират с <ol> елемент, неподредените с <ul> елемент а дефиниционните списъци с <dl> елемент.

Подредените и неподредените списъци съдържат редове обозначени с <li> елемент. Редовете могат да съдържат текст или могат да бъдат пакетирани в един или повече <p> елементи.

Списъците с дефиниции съдържат дефиниционни термини (<dt>) и описания (<dd>). Дефиниционния термин може да съдържа само вградени в линията елементи. Описанието обаче, може да съдържа други блокови елементи.

Example 4-6. <ul> и <ol>

използване:

<p>An unordered list.  Listitems will probably be
  preceded by bullets.</p>

<ul>
  <li>First item</li>

  <li>Second item</li>

  <li>Third item</li>
</ul>

<p>An ordered list, with list items consisting of multiple
  paragraphs.  Each item (note: not each paragraph) will be
  numbered.</p>

<ol>
  <li><p>This is the first item.  It only has one paragraph.</p></li>

  <li><p>This is the first paragraph of the second item.</p>

    <p>This is the second paragraph of the second item.</p></li>

  <li><p>This is the first and only paragraph of the third
    item.</p></li>
</ol>

Example 4-7. Списъци дефиниции с <dl>

Използване:

<dl>
  <dt>Term 1</dt>

  <dd><p>Paragraph 1 of definition 1.</p></dd>

    <p>Paragraph 2 of definition 1.</p></dd>

  <dt>Term 2</dt>

  <dd><p>Paragraph 1 of definition 2.</p></dd>

  <dt>Term 3</dt>

  <dd>Paragraph 1 of definition 3.  Note that the &lt;p&gt;
    element is not required in the single paragraph case.</dd>
</dl>

4.1.3.5 Пре-форматиран текст

Можете да укажете, че част от текста трябва да бъде показан на потребителя точно както е във файла. Обикновенно това означава, че текста ще бъде показан с фиксиран шрифт, съседни интервали няма да бъдат заменяни с един и нов ред в линия ще бъде изпълнен.

За постигнете това, пакетирайте съдържанието в <pre> елемент.

Example 4-8. <pre>

Можете да използвате <pre>, за да маркирате e-mail;

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

  There is a new copy of my primer for contributors to the FreeBSD
  Documentation Project available at

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

  Comments appreciated.

  N</pre>

4.1.3.6 Таблици

Note: Повечето текстови браузери (като Lynx) не показват таблици особено ефективно. Ако разчитате на табулирано показване на съдържанието, помислете за алтернативно маркиране, за да избегнете объркване.

Маркирайте табулирана информация чрез <table> елемент. Таблиците се състоят от един или повече редове (<tr>) всеки съдържащ една или повече клетки таблични данни (<td>). Всяка клетка може да съдържа други блокови елементи, като параграфи или списъци. Може да съдържа и друга таблица (тази серия може да се повтаря неограничено). Ако клетката съдържа само един параграф, не е необходимо да включвате <p> елемент.

Example 4-9. Примери за приложение на <table>

Използване:

<p>This is a simple 2x2 table.</p>

<table>
  <tr>
    <td>Top left cell</td>

    <td>Top right cell</td>
  </tr>

  <tr>
    <td>Bottom left cell</td>

    <td>Bottom right cell</td>
  </tr>
</table>

Клетка може да се простира на няколко реда и колони. За укажете това използвайте атрибутите rowspan и/или colspan със стойности показващи броя редове на колоните върху които трябва се разпростира клетката.

Example 4-10. Приложение на rowspan

Използване:

<p>One tall thin cell on the left, two short cells next to
  it on the right.</p>

<table>
  <tr>
    <td rowspan="2">Long and thin</td>
  </tr>

  <tr>
    <td>Top cell</td>

    <td>Bottom cell</td>
  </tr>
</table>

Example 4-11. Приложение на colspan

Използване:

<p>One long cell on top, two short cells below it.</p>

<table>
  <tr>
    <td colspan="2">Top cell</td>
  </tr>

  <tr>
    <td>Bottom left cell</td>

    <td>Bottom right cell</td>
  </tr>
</table>

Example 4-12. Приложение на rowspan и colspan заедно

Използване:

<p>On a 3x3 grid, the top left block is a 2x2 set of
  cells merged into one.  The other cells are normal.</p>

<table>
  <tr>
    <td colspan="2" rowspan="2">Top left large cell</td>

    <td>Top right cell</td>
  </tr>

  <tr>
    <!-- Because the large cell on the left merges into
         this row, the first <td> will occur on its
         right -->
        
    <td>Middle right cell</td>
  </tr>

  <tr>
    <td>Bottom left cell</td>

    <td>Bottom middle cell</td>

    <td>Bottom right cell</td>
  </tr>
</table>

4.1.4 Елементи в линията

4.1.4.1 Подчертаване

В HTML разполагате с две нива на подчертаване, <em> и <strong>. <em> е за нормално ниво на подчертаване а <strong> предизвиква силно подчертаване.

Обикновенно, <em> се показва с наклонен шрифт а <strong> се показва като удебелен. Това не винаги е така и не би трябвало да разчитате само на това.

Example 4-13. <em> и <strong>

Използване:

<p><em>This</em> has been emphasised, while
  <strong>this</strong> has been strongly emphasised.</p>

4.1.4.2 Удебелени и наклонени

HTML включва маркиране с което можете да укажете, че определено съдържание трябва да се покаже в удебелен или наклонен шрифт. Елементите са. <b> и <i> респективно.

Example 4-14. <b> и <i>

<p><b>This</b> is in bold, while <i>this</i> is
  in italics.</p>

4.1.4.3 Означаване на текст с фиксирано подреждане

Ако имате съдържание, което трябва да бъде показано като текст с фиксирано подреждане (машинописно), използвайте <tt> (за ``teletype'').

Example 4-15. <tt>

Използване:

<p>This document was originally written by
  Nik Clayton, who can be reached by e-mail as
  <tt>nik@FreeBSD.org</tt>.</p>

4.1.4.4 Размер на съдържанието

Можете да укажете, че съдържание трябва да бъде показано в по-голям или по-малък шрифт. Има три начина да постигнете това.

  1. Използване на <big> и <small> около съдържанието на което искате да промените размера. Тези етикети могат да бъдат наслагвани, така че <big><big>Това е много по-голямо </big></big> е допустимо.

  2. Използване на <font> с size атрибут +1 или -1 респективно. Това има същият ефект като използването на <big> или <small>. Все пак, използването му е нежелателно.

  3. Използване на <font> с size атрибут инциализиран с цифра между 1 и 7. Размера на шрифта по подразбиране е 3. Използването на този начин не се препоръчва.

Example 4-16. <big>, <small> и <font>

Следният пример представя едно и също нещо.

<p>This text is <small>slightly smaller</small>.  But
  this text is <big>slightly bigger</big>.</p>

<p>This text is <font size="-1">slightly smaller</font>.  But
  this text is <font size="+1">slightly bigger</font.</p>

<p>This text is <font size="2">slightly smaller</font>.  But
  this text is <font size="4">slightly bigger</font>.</p>

4.1.5 Препратки

Note: Препратките също са линейни елементи.

4.1.5.1 Препращане към други документи в WWW

За да можете да включите препратка към друг документ от WWW трябва да знаете URL на документа, които искате да включите.

Препратката се означава с <a> и href атрибут съдържащ URL на документа цел. Съдържанието на документа става препратка и обикновенно се означава за потребителя по някакъв начин (подчертаване, смяна на цвета, друг курсор на мишката когато е върху препратката и т.н.).

Example 4-17. Пример за <a href="...">

Използване:

<p>More information is available at the
  <a href="http://www.FreeBSD.org/">FreeBSD web site</a>.</p>

Такива препратки ще изпратят потребителя в началото на избран документ.

4.1.5.2 Препращане към други части на документи

Препращането към част от друг документ (или в текущия) изисква автора да е включил котви към които можете да препращате.

Котви се означават с <a> и name атрибути вместо href.

Example 4-18. Пример за <a name="...">

Използване:

<p><a name="para1">This</a> paragraph can be referenced
  in other links with the name <tt>para1</tt>.</p>

За да препратите към наименувана част на документ, сложете нормална препратка към документа, но включете името на котвата след # знак.

Example 4-19. Препращане към част от друг документ

Да предположим, че para1 пример се намира в документ наречен foo.html.

<p>More information can be found in the
  <a href="foo.html#para1">first paragraph</a> of
  <tt>foo.html</tt>.</p>

Ако препращате към наименувана котва в същият документ, можете да прескочите URL на текущия документ - просто включете името на котвата (с предхождащ #).

Example 4-20. Препращане към част от текущия документ

Да предположим, че para1 пример се намира в този документ

<p>More information can be found in the
  <a href="#para1">first paragraph</a> of this
  document.</p>

Този и други документи можете да намерите в ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/.

За въпроси отностно FreeBSD, прочетете документацията преди да попитате в <questions@FreeBSD.org>.
За въпроси отностно този документ, e-mail <doc@FreeBSD.org>.