The OpenNET Project / Index page

[ новости /+++ | форум | wiki | теги | ]

Поиск:  Каталог документации / Документация по FreeBSD / Руководства по FreeBSD на английском

3.8. Marked sections

SGML provides a mechanism to indicate that particular pieces of the document should be processed in a special way. These are termed ``marked sections''.

Example 3-14. Structure of a marked section

    <![ KEYWORD [
      Contents of marked section
    ]]>

As you would expect, being an SGML construct, a marked section starts with <!.

The first square bracket begins to delimit the marked section.

KEYWORD describes how this marked section should be processed by the parser.

The second square bracket indicates that the content of the marked section starts here.

The marked section is finished by closing the two square brackets, and then returning to the document context from the SGML context with >

3.8.1. Marked section keywords

3.8.1.1. CDATA, RCDATA

These keywords denote the marked sections content model, and allow you to change it from the default.

When an SGML parser is processing a document it keeps track of what is called the ``content model''.

Briefly, the content model describes what sort of content the parser is expecting to see, and what it will do with it when it finds it.

The two content models you will probably find most useful are CDATA and RCDATA.

CDATA is for ``Character Data''. If the parser is in this content model then it is expecting to see characters, and characters only. In this model the < and & symbols lose their special status, and will be treated as ordinary characters.

RCDATA is for ``Entity references and character data'' If the parser is in this content model then it is expecting to see characters and entities. < loses its special status, but & will still be treated as starting the beginning of a general entity.

This is particularly useful if you are including some verbatim text that contains lots of < and & characters. While you could go through the text ensuring that every < is converted to a &lt; and every & is converted to a &amp;, it can be easier to mark the section as only containing CDATA. When the SGML parser encounters this it will ignore the < and & symbols embedded in the content.

Example 3-15. Using a CDATA marked section

    <para>Here is an example of how you would include some text
      that contained many &lt; and &amp; symbols.  The sample
      text is a fragment of HTML.  The surrounding text (<para> and
      <programlisting>) are from DocBook.</para>
    
    <programlisting>
      <![ CDATA [  
        <p>This is a sample that shows you some of the elements within
          HTML.  Since the angle brackets are used so many times, it's
          simpler to say the whole example is a CDATA marked section
          than to use the entity names for the left and right angle
          brackets throughout.</p>
    
        <ul>
          <li>This is a listitem</li>
          <li>This is a second listitem</li>
          <li>This is a third listitem</li>
        </ul>
    
        <p>This is the end of the example.</p>
      ]]>
    </programlisting>

If you look at the source for this document you will see this technique used throughout.

3.8.1.2. INCLUDE and IGNORE

If the keyword is INCLUDE then the contents of the marked section will be processed. If the keyword is IGNORE then the marked section is ignored and will not be processed. It will not appear in the output.

Example 3-16. Using INCLUDE and IGNORE in marked sections

    <![ INCLUDE [
      This text will be processed and included.
    ]]>
    
    <![ IGNORE [
      This text will not be processed or included.
    ]]>

By itself, this isn't too useful. If you wanted to remove text from your document you could cut it out, or wrap it in comments.

It becomes more useful when you realise you can use parameter entities to control this. Remember that parameter entities can only be used in SGML contexts, and the keyword of a marked section is an SGML context.

For example, suppose that you produced a hard-copy version of some documentation and an electronic version. In the electronic version you wanted to include some extra content that wasn't to appear in the hard-copy.

Create a parameter entity, and set it's value to INCLUDE. Write your document, using marked sections to delimit content that should only appear in the electronic version. In these marked sections use the parameter entity in place of the keyword.

When you want to produce the hard-copy version of the document, change the parameter entity's value to IGNORE and reprocess the document.

Example 3-17. Using a parameter entity to control a marked section

    <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
    <!ENTITY % electronic.copy "INCLUDE">         
    ]]>
    
    ...
    
    <![ %electronic.copy [
      This content should only appear in the electronic
      version of the document.
    ]]>

When producing the hard-copy version, change the entity's definition to;

    <!ENTITY % electronic.copy "IGNORE">

On reprocessing the document, the marked sections that use %electronic.copy as their keyword will be ignored.

3.8.2. For you to do...

  1. Create a new file, section.sgml, that contains the following;

        <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
        <!ENTITY % text.output "INCLUDE">
        ]>
        
        <html>
          <head>
            <title>An example using marked sections</title>
          </head>
        
          <body>     
            <p>This paragraph <![ CDATA [contains many <
              characters (< < < < <) so it is easier
              to wrap it in a CDATA marked section ]]></p>
        
            <![ IGNORE [
            <p>This paragraph will definitely not be included in the
              output.</p>
            ]]>
        
            <![ %text.output [
            <p>This paragraph might appear in the output, or it
              might not.</p>
        
            <p>Its appearance is controlled by the %text.output
              parameter entity.</p>      
            ]]>
          </body>
        </html>
    
  2. Normalise this file using sgmlnorm(1) and examine the output. Notice which paragraphs have appeared, which have disappeared, and what has happened to the content of the CDATA marked section.

  3. Change the definition of the text.output entity from INCLUDE to IGNORE. Re-normalise the file, and examine the output to see what has changed.

For questions about FreeBSD, e-mail <questions@FreeBSD.org>.
For questions about this documentation, e-mail <doc@FreeBSD.org>.




Спонсоры:
Inferno Solutions
Hosting by Hoster.ru
Хостинг:

Закладки на сайте
Проследить за страницей
Created 1996-2021 by Maxim Chirkov
Добавить, Поддержать, Вебмастеру