referencia-html/agrupando-contenido.rst

===================
Agrupando contenido
===================

El elemento ``p``
=================

Representa un párrafo.

.. code-block:: html

     <p>Un párrafo es una unidad comunicativa formada por un conjunto de
     oraciones secuenciales que trata un mismo tema.</p>

.. code-block:: html

     <fieldset>
       <legend>Información personal</legend>
       <p>
         <label>Nombre: <input name="n"></label>
         <label><input name="anon" type="checkbox"> Mantener anónimo</label>
       </p>
       <p><label>Dirección: <textarea name="a"></textarea></label></p>
     </fieldset>

.. code-block:: html

     <p>No me contéis más cuentos,<br>
     que vengo de muy lejos<br>
     y sé todos los cuentos.<br>
     No me contéis más cuentos.</p>

El elemento ``<p>`` no debería ser usado cuando existe un elemento más
específico y apropiado.

El siguiente ejemplo es técnicamente correcto...

.. code-block:: html

     <section>
       <!-- ... -->
       <p>Modificado: 2002-05-24</p>
       <p>Autor: nombre@ejemplo.com</p>
     </section>

Sin embargo, es más correcto utilizar etiquetas más concretas...

.. code-block:: html

     <section>
       <!-- ... -->
       <footer>Modificado: 2002-05-24</footer>
       <address>Autor: nombre@ejemplo.com</address>
     </section>

.. code-block:: html

     <section>
       <!-- ... -->
       <footer>
         <p>Modificado: 2002-05-24</p>
         <address>Autor: nombre@ejemplo.com</address>
       </footer>
     </section>

Los elementos de listas (en concreto, los elementos ``<ol>`` y ``<ul>``) no pueden ser hijos de elementos ``<p>``.

En términos de HTML, un párrafo no es un concepto lógico, sino
estructural. Según la especificación de HTML 5.1 en el siguiente ejemplo
hay cinco párrafos: uno antes de la lista, uno para cada viñeta y otro después
de la lista.

.. code-block:: html

     <p>Por ejemplo, está fantástica oración tiene viñetas relacionadas con</p>
     <ul>
       <li>magos,
       <li>viajes en el tiempo y
       <li>telepatía,
     </ul>
     <p>y no tiene sentido.</p>

Si quisieramos dar formato a ese párrafo «lógico», podríamos utilizar el
elemento ``<div>`` en vez del elemento ``<p>``.

.. code-block:: html

     <div>Por ejemplo, está fantástica oración tiene viñetas relacionadas con
     <ul>
       <li>magos,
       <li>viajes en el tiempo y
       <li>telepatía,
     </ul>
     y no tiene sentido.</div>

El elemento ``hr``
==================

Representa una división temática, por ejemplo, un
cambio de escenario en una historia o una transición a otra dentro
de una sección de un libro de referencia.

.. code-block:: html

     <section>
       <h1>Communication</h1>
       <p>There are various methods of communication. This section
       covers a few of the important ones used by the project.</p>
       <hr>
       <p>Communication stones seem to come in pairs and have mysterious
       properties:</p>
       <ul>
         <li>They can transfer thoughts in two directions once activated
         if used alone.</li>
         <li>If used with another device, they can transfer one’s
         consciousness to another body.</li>
         <li>If both stones are used with another device, the
         consciousnesses switch bodies.</li>
       </ul>
       <hr>
       <p>Radios use the electromagnetic spectrum in the meter range and
       longer.</p>
       <hr>
       <p>Signal flares use the electromagnetic spectrum in the
       nanometer range.</p>
     </section>
     <section>
       <h1>Food</h1>
       <p>All food at the project is rationed:</p>
       <dl>
         <dt>Potatoes</dt>
         <dd>Two per day</dd>
         <dt>Soup</dt>
         <dd>One bowl per day</dd>
       </dl>
       <hr>
       <p>Cooking is done by the chefs on a set rotation.</p>
     </section>

En el anterior ejemplo, no hay necesidad de usar el elemento ``<hr>``, puesto
que los elementos ``<section>`` y ``<h1>`` implican un cambio temático por
sí mismos.

A continuación, se muestra un extracto de *Scholarium* de Claudia Gross. En
el libro, el cambio de escena se representa con dos espacios antes del nuevo
párrafo. Aquí se representa con el elemento ``<hr>``.

.. code-block:: html

     <p>Subió las escaleras a toda prisa. La ventana de la habitación
     estaba abierta; la cerró de golpe y, por fin, encendió la luz.</p>
     <hr>
     <p>—Y si el cielo fuera amarillo como un limón, también lo querríais
     demostrar. ¿Conocéis la teoría de la doble verdad de Duns Escoto?
     Afirma que algo puede ser verdadero y falso a la vez, dependiendo
     únicamente del ángulo desde donde se mire. Y yo pregunto: ¿qué punto
     de vista sostenéis vosotros?</p>



El elemento ``pre``
===================

Representa un bloque de texto preformateado, en el cual la estructura se
representa por convenciones tipográficas en vez de por elementos.

A continuación, citamos algunos ejemplos de casos en los que el elemento
``<pre>`` podría ser usado:

- Incluyendo un email, con párrafos rodeados de líneas en blanco, listas
  indicadas por líneas con una viñeta, etc.

- Para incluir fragmentos de código, con una estructura acorde con las
  convenciones de ese lenguage.

- Para mostrar arte ASCII.

  .. code-block:: html

       <pre>
                      ,
                     / \,,_  .'|
                  ,{{| /}}}}/_.'            _____________________________________________
                 }}}}` '{{'  '.            /                                             \
               {{{{{    _   ;, \          /            Ladies and Gentlemen,              \
            ,}}}}}}    /o`\  ` ;)        |                                                |
           {{{{{{   /           (        |                 this is ...                    |
           }}}}}}   |            \       |                                                |
          {{{{{{{{   \            \      |                                                |
          }}}}}}}}}   '.__      _  |     |    _____             __             __  _      |
          {{{{{{{{       /`._  (_\ /     |   / ___/__  ______  / /_____ ______/ /_(_)____ |
           }}}}}}'      |    //___/   --=:   \__ \/ / / / __ \/ __/ __ `/ ___/ __/ / ___/ |
       jgs `{{{{`       |     '--'       |  ___/ / /_/ / / / / /_/ /_/ (__  ) /_/ / /__   |
            }}}`                         | /____/\__, /_/ /_/\__/\__,_/____/\__/_/\___/   |
                                         |      /____/                                    |
                                         |                                               /
                                          \_____________________________________________/</pre>

Para representar un bloque de código, el elemento ``<pre>`` puede ser
usado con un elemento ``<code>``; para representar
la salida de un programa, el elemento ``<pre>`` puede combinarse con el
elemento ``<samp>``; y para
indicar el texto que el usuario debe introducir, puede combinarse el elemento
``<pre>`` con el elemento ``<kbd>``.

El siguiente ejemplo de código muestra combina los elementos ``<pre>`` y
``<code>`` para mostrar el código de una función.

.. code-block:: html

     <p>Este es el constructor <code>Panel</code>:</p>
     <pre><code>function Panel(element, canClose, closeHandler) {
       this.element = element;
       this.canClose = canClose;
       this.closeHandler = function () { if (closeHandler) closeHandler() };
     }</code></pre>

En el siguiente fragmento de código los elementos ``<samp>`` y ``<kbd>`` se
combinan para mostrar una sesión de Zork I.

.. code-block:: html

     <pre><samp>You are in an open field west of a big white house with a boarded
     front door.
     There is a small mailbox here.

     ></samp> <kbd>open mailbox</kbd>

     <samp>Opening the mailbox reveals:
     A leaflet.

     ></samp></pre>

El siguiente ejemplo de código muestra un poema contemporáneo, usando la
etiqueta ``<pre>`` para preservar los espacios, que forman parte del poema.

.. code-block:: html

     <pre>                maxling

     it is with a          heart
                     heavy

     that i admit loss of a feline
             so           loved

     a friend lost to the
             unknown
                                     (night)

     ~cdr 11dec07</pre>

El elemento ``blockquote``
==========================

Representa contenido citado de otra fuente, opcionalmente con una cita que
debe ser escrita en el elemento ``<footer>`` o ``<cite>``, y opcionalmente con
cambios como anotaciones y abreviaciones.

.. code-block:: html

     <figure>
     <blockquote>Sólo por propósitos comerciales, Google, [...]
     están coleccionando enormes cantidades de información de las personas
     [...]. Rastrean tus hábitos,
     tus compras, tu comportamiento, lo que haces y están tratando de
     controlarte dirigiéndote en determinadas direcciones.
     Y creo que lo están haciendo en niveles que exceden a lo que el gobierno hace.
     Así que el gobierno les está pidiendo ayuda.</blockquote>
     <footer>
       <cite class="title">¿Por qué Chomsky desconfía de internet?</cite> por
       <cite class="author">Noam Chomsky</cite>, por <a href="http://www.bbc.com/mundo/noticias/2013/07/130702_chomsky_internet_digital_criticas_pmt.shtml">BBC Mundo</a>
     </footer>
     </figure>

La atribución de la cita puede ser ubicada dentro de un elemento ``<cite>``.

.. code-block:: html

     <blockquote>
       The people recognize themselves in their commodities; they find their
       soul in their automobile, hi-fi set, split-level home, kitchen equipment.
       — <cite><a href="https://en.wikipedia.org/wiki/Herbert_Marcuse">Herbert Marcuse</a></cite>
     </blockquote>

El elemento ``ol``
==================

Representa una lista de elementos en la que los elementos han sido ordenados
intencionadamente, de forma que cambiar su orden cambiaría el significado del
documento.

Los componentes de la lista son elementos ``<li>`` hijos del elemento ``<ol>``.

El elemento ``<ol>`` puede acompañarse de algunos atributos propios que
cambian su significado:

- El atributo ``reversed`` es un booleano. Si está presente, indica que el
  orden de la lista es descendente (..., 3, 2, 1). Si se omite, el orden de la
  lista es ascendente (1, 2, 3, ...).

- El atributo ``start``, si se indica, debe ser un número entero que indique
  el valor ordinal del primer elemento.

- El atributo ``type`` puede ser utilizado para indicar el tipo de marca
  utilizado en la lista, en casos en los que es importante (por ejemplo, porque
  se hace referencia a sus elementos a través de su número o letra). Este
  atributo puede tener los siguientes valores:

  - decimal
  - lower-alpha
  - upper-alpha
  - lower-roman
  - upper-roman

  Cabe tener en cuenta que los números iguales o menores que cero siempre
  usarán el sistema decimal, ignorando el atributo ``type``.

.. code-block:: html

     <p>He vivido en los seguientes países (ordenados según la primera vez
     que viví en ellos):</p>
     <ol>
       <li>Cuba</li>
       <li>Italia</li>
       <li>Argentina</li>
       <li>Ecuador</li>
     </ol>

El elemento ``ul``
==================

Representa una lista de elementos en la que el orden de los elementos no es
importante, es decir, cambiar el orden de los elementos no altera el
significado del documento.

Los componentes de la lista son elementos ``<li>`` hijos del elemento ``<ul>``.

.. code-block:: html

     <p>He vivido en los seguientes países:</p>
     <ul>
       <li>Cuba</li>
       <li>Italia</li>
       <li>Argentina</li>
       <li>Ecuador</li>
     </ul>

El elemento ``li``
==================

Representa un elemento de una lista. Su elemento padre puede ser ``<ol>``,
``<ul>`` o ``<menu>``.

Si su elemento padre es ``<ol>``, el elemento ``<li>`` tiene un valor ordinal.
Este valor se puede modificar a través del atributo ``value``

.. code-block:: html

     <figure>
        <figcaption>
          Los cinco mejores libros
          (todavía no sabemos cuáles son el número 4 y el 1)
        </figcaption>
        <ol>
          <li value="5" lang="de"><cite>Die Verwandlung</cite></li>
          <li value="3"><cite>El Quijote</cite></li>
          <li value="2"><cite>Guerra y Paz</cite></li>
        </ol>
     </figure>

El elemento ``dl``
==================

Representa una lista descriptiva de grupos de términos y descripciones.
Cada grupo de términos y descripciones consiste en uno o más términos
(representados por elementos ``<dt>``) y una o más descripciones
(representadas por elementos ``<dd>``).

Los grupos término-descriptivos pueden ser nombres y definiciones,
preguntas y respuestas, categorías y tópicos...

.. code-block:: html

     <dl>
       <dt><em>C-b</em></dt>
       <dd>Se mueve atrás un carácter.</dd>
       <dt><em>C-f</em></dt>
       <dd>Se mueve adelante un carácter.</dd>
     </dl>

En el siguiente ejemplo cada elemento ``<dt>`` tiene asociados varios
``<dd>``...

.. code-block:: html

     <p>Información sobre el grupo de rock Queen:</p>
     <dl>
       <dt>Miembros</dt>
       <dd>Brian May</dd>
       <dd>Freddie Mercury</dd>
       <dd>John Deacon</dd>
       <dd>Roger Taylor</dd>
       <dt>Discográficas</dt>
       <dd>EMI</dd>
       <dd>Parlophone</dd>
       <dd>Capitol</dd>
       <dd>Hollywood</dd>
       <dd>Island</dd>
     </dl>

El elemento ``dt``
==================

Representa un término que forma parte de un grupo término-descriptivo
en una lista descriptiva (elemento ``<dl>``).

El elemento ``dd``
==================

Representa una descripción que forma parte de un grupo término-descriptivo
en una lista descriptiva (elemento ``<dl>``).

El elemento ``figure``
======================

Representa `contenido de flujo <https://www.w3.org/TR/html51/dom.html#flow-content>`__,
opcionalmente con una leyenda, al que se hace referencia como una
únidad en el flujo del documento. Puede ser utilizado para mostrar
ilustraciones, diagramas, fotografías, etc.

.. code-block:: html

     <figure>
       <img src="mazana.png" alt="Manzana" />
       <figcaption>
         Breve descripción de la manzana.
       </figcaption>
     </figure>

.. code-block:: html

     <figure>
       <video src="trailer-pelicula.ogg"></video>
       <figcaption>Trailer de la película</figcaption>
     </figure>


El elemento ``figcaption``
==========================

Representa la descripción o leyenda del contenido de su elemento padre
``<figure>``.

El elemento ``main``
====================

Representa el contenido principal del cuerpo (``<body>``) del documento
o aplicación.

El área de contenido principal de un documento incluye contenido que es
único de ese documento y excluye contenido que se repite en varios documentos,
como pueden ser enlaces de navegación, información de copyright,
logotipos de la página, banners y formularios de búsqueda (a no ser
que la función principal del documento o aplicación sea la de un formulario
de búsqueda).

En el siguiente ejemplo, podemos ver dos artículos relacionados con
manzanas (el tema principal de la página web).

.. code-block:: html

     <!-- otro contenido secundario... -->

     <main>
       <h1>Manzanas</h1>
       <p>La manzana es una fruta pomácea comestible fruto del manzano.</p>

       <article>
         <h2>Manzana roja</h2>
         <p>Estas brillantes manzanas rojas son comunes...</p>
         <p>...</p>
         <p>...</p>
       </article>

       <article>
         <h2>Manzana verde</h2>
         <p>Esta clase de manzana se encuentra en...</p>
         <p>...</p>
         <p>...</p>
       </article>
    </main>

    <!-- otro contenido secundario... -->

El elemento ``div``
===================

El elemento ``<div>`` no tiene un significado especial. Representa a sus hijos.
Puede ser usado con otros atributos como ``class``, ``lang`` y ``title``.

Se recomienda utilizar el elemento ``<div>`` como un último recurso, cuando
ningún otro elemento es adecuado.

Se suele utilizar mucho para dar estilo a regiones de una página web haciendo
uso de los atributos ``class`` e ``id`` y de reglas CSS.

En el siguiente ejemplo se usa el elemento ``<div>`` para indicar que parte
de un párrafo está escrita en otro idioma que no es el principal de la
página.

.. code-block:: html

      <p>Debería escribir solo en castellano, <div lang="de">aber ich
      habe keine Lust</div></p>