Manual Debian Live

Acerca de este manual

1. Acerca de este manual

1.1 Para el impaciente.
1.2 Términos
1.3 Autores
1.4 Cómo contribuir en este documento
1.4.1 Aplicar cambios
1.4.2 Traducción

2. Acerca del Proyecto Debian Live

2.1 Motivación
2.1.1 Desventajas en los sistemas Live actuales
2.1.2 El porqué de crear un Sistema Live propio.
2.2 Filosofía
2.2.1 Solamente paquetes sin modificación alguna de Debian «main»
2.2.2 Sin configuración especial para el Sistema Live
2.3 Contacto

Usuario

3. Instalación

3.1 Requisitos
3.2 Instalación de live-build
3.2.1 Desde el repositorio Debian.
3.2.2 A partir del código fuente
3.2.3 A partir de «instantáneas»
3.3 Instalación de live-boot y live-config
3.3.1 Desde el repositorio Debian.
3.3.2 A partir del código fuente
3.3.3 A partir de «instantáneas»

4. Conceptos básicos

4.1 ¿Qué es un sistema en vivo?
4.2 Primeros pasos: creación de una imagen ISO híbrida
4.3 Usar una imagen ISO híbrida
4.3.1 Grabar una imagen ISO en un medio físico.
4.3.2 Copiar una imagen ISO híbrida a un dispositivo USB
4.3.3 Arrancar los medios en vivo
4.4 Usar una máquina virtual para pruebas
4.4.1 Probar una imagen ISO con QEMU
4.4.2 Probar una imagen ISO con virtualbox-ose
4.5 Crear una imagen HDD
4.6 Utilizar una imágen HDD
4.6.1 Probar una imágen HDD con Qemu
4.6.2 Usar el espacio libre en el dispositivo USB
4.7 Creación de una imagen de arranque en red
4.7.1 Servidor DHCP
4.7.2 Servidor TFTP
4.7.3 Servidor NFS
4.7.4 Cómo probar el arranque en red
4.7.5 Qemu
4.7.6 VMWare Player

5. Descripción general de las herramientas

5.1 El paquete live-build
5.1.1 El comando lb config
5.1.2 El comando lb build
5.1.3 El comando lb clean
5.2 El paquete live-boot
5.3 El paquete live-config

6. Gestionar una configuración

6.1 Utilización de auto para gestionar los cambios de la configuración
6.2 Un ejemplo de scripts auto.

7. Descripción general de la personalización.

7.1 Configuración en el momento de la creación vs en el momento del arranque
7.2 Etapas de la creación
7.3 Opciones para lb config en ficheros
7.4 Tareas de personalización

8. Personalización de la instalación de paquetes

8.1 Origen de los paquetes
8.1.1 Distribución, áreas de archivo y modo
8.1.2 Réplicas de Distribución Debian
8.1.3 Réplicas de Distribution utilizadas durante la creación
8.1.4 Réplicas de distribución Debian utilizadas en la ejecución.
8.1.5 Repositorios adicionales
8.2 Selección de los paquetes a instalar
8.2.1 Listas de paquetes
8.2.2 Listas de paquetes predefinidas
8.2.3 Listas de paquetes locales
8.2.4 Listas de paquetes locales para binary
8.2.5 Extensión de una lista de paquetes dada mediante «includes»
8.2.6 Utilización de condiciones dentro de las listas de paquetes
8.2.7 Tareas
8.2.8 Tareas de Escritorio e Idioma
8.3 Instalar paquetes de terceros o paquetes modificados
8.3.1 Método packages.chroot para instalar paquetes personalizados
8.3.2 Método de repositorio APT para instalar paquetes personalizados
8.3.3 Paquetes personalizados y APT
8.4 Configurar APT en la creación
8.4.1 Utilizar apt o aptitude
8.4.2 Utilización de un proxy con APT
8.4.3 Ajuste de APT para ahorrar espacio
8.4.4 Pasar opciones a apt o a aptitude
8.4.5 APT pinning

9. Personalización de contenidos

9.1 Includes
9.1.1 Includes locales en Live/chroot
9.1.2 Includes locales en Binary
9.1.3 Includes en Binary
9.2 Scripts gancho (Hooks)
9.2.1 Scripts gancho locales en Live/chroot
9.2.2 Scripts gancho en tiempo de arranque
9.2.3 Scripts gancho locales en Binary
9.3 Preconfiguración de las preguntas de Debconf

10. Personalización del comportamiento en tiempo de ejecución.

10.1 Personalización del usuario por defecto del sistema en vivo
10.2 Personalización de las variantes locales e idioma
10.3 Persistencia
10.3.1 El fichero live-persistence.conf
10.3.2 SubText persistente

11. Personalización de la imagen binaria

11.1 Gestor de arranque
11.2 Metadatos ISO

12. Personalización del Instalador de Debian

12.1 Tipos de imágenes según el instalador
12.2 Personalizando el Instalador de Debian mediante preconfiguración
12.3 Personalizar el contenido del Instalador de Debian

Proyecto

13. Informes de errores.

13.1 Problemas conocidos
13.2 Reconstruir desde cero
13.3 Utilizar paquetes actualizados
13.4 Recopilar información
13.5 Aislar el fallo si es posible
13.6 Utilizar el paquete correcto sobre el que informar del error
13.6.1 En la preinstalación (bootstrap) en tiempo de creación.
13.6.2 Mientras se instalan paquetes en tiempo de creación.
13.6.3 En tiempo de arranque
13.6.4 En tiempo de ejecución
13.7 Hacer la investigación
13.8 Dónde informar de los fallos

14. Estilo de código

14.1 Compatibilidad
14.2 Sangrado
14.3 Ajuste de líneas
14.4 Variables
14.5 Miscelánea

15. Procedimientos

15.1 Subir Udebs
15.2 Principales lanzamientos
15.3 Nuevas versiones
15.3.1 Última actualización de una versión Debian
15.3.2 Plantilla para anunciar nuevas versiones.

Ejemplos

16. Ejemplos

16.1 Uso de los ejemplos
16.2 Tutorial 1: Una imagen estándar
16.3 Tutorial 2: Una utilidad de navegador web
16.4 Tutorial 3: Una imagen personalizada
16.4.1 Primera revisión
16.4.2 Segunda revisión
16.5 Un cliente VNC kiosk
16.6 Una imagen básica para un pendrive USB de 128M
16.7 Un escritorio KDE con variante local e instalador

Apéndice

17. Style guide

17.1 Guidelines for authors
17.1.1 Linguistic features
17.1.2 Procedures
17.2 Guidelines for translators
17.2.1 Translation hints

Manual Debian Live

Apéndice

17. Style guide

17.1 Guidelines for authors

This section deals with some general considerations to be taken into account when writing technical documentation for live-manual. They are divided into linguistic features and recommended procedures.

Note: Authors should first read Contributing to this document

17.1.1 Linguistic features

  • Use plain English
  • Keep in mind that a high percentage of your readers are not native speakers. So as a general rule try to use short, meaningful sentences, followed by a full stop.

    This does not mean that you have to use a simplistic, naive style. It is a suggestion to try to avoid, as much as possible, complex subordinate sentences that make the text difficult to understand for non-native speakers.

  • Variety of English
  • The most widely spread varieties of English are British and American so it is very likely that most authors will use either one or the other. In a collaborative environment, the ideal variety would be "International English" but it is very difficult, not to say impossible, to decide on which variety among all the existing ones, is the best to use.

    We expect that different varieties may mix without creating misunderstandings but in general terms you should try to be coherent and before deciding on using British, American or any other English flavour at your discretion, please take a look at how other people write and try to imitate them.

  • Be balanced
  • Do not be biased. Avoid including references to ideologies completely unrelated to live-manual. Technical writing should be as neutral as possible. It is in the very nature of scientific writing.

  • Be politically correct
  • Try to avoid sexist language as much as possible. If you need to make references to the third person singular preferably use "they" rather than "he" or "she" or awkward inventions such as "s/he", "s(he)" and the like.

  • Be concise
  • Go straight to the point and do not wander around aimlessly. Give as much information as necessary but do not give more information than necessary, this is to say, do not explain unnecessary details. Your readers are intelligent. Presume some previous knowledge on their part.

  • Minimize translation work
  • Keep in mind that whatever you write will have to be translated into several other languages. This implies that a number of people will have to do an extra work if you add useless or redundant information.

  • Be coherent
  • As suggested before, it is almost impossible to standardize a collaborative document into a perfectly unified whole. However, every effort on your side to write in a coherent way with the rest of the authors will be appreciated.

  • Be cohesive
  • Use as many text-forming devices as necessary to make your text cohesive and unambiguous. (Text-forming devices are linguistic markers such as connectors).

  • Be descriptive
  • It is preferable to describe the point in one or several paragraphs than merely using a number of sentences in a typical "changelog" style. Describe it! Your readers will appreciate it.

  • Dictionary
  • Look up the meaning of words in a dictionary or encyclopedia if you do not know how to express certain concepts in English. But keep in mind that a dictionary can either be your best friend or can turn into your worst enemy if you do not know how to use it correctly.

    English has the largest vocabulary that exists (With over one million words). Many of these words are borrowings from other languages. When looking up the meaning of words in a bilingual dictionary the tendency of a non-native speaker is to choose the one that sounds more similar in their mother tongue. This often turns into an excessively formal discourse which does not sound quite natural in English.

    As a general rule, if a concept can be expressed using different synonyms, it is a good advice to choose the first word proposed by the dictionary. If in doubt, choosing words of Germanic origin (Usually monosyllabic words) is often the right thing to do. Be warned that these two techniques might produce a rather informal discourse but at least your choice of words will be of wide use and generally accepted.

    Using a dictionary of collocations is recommended. They are extremely helpful when it comes to know which words usually occur together.

    Again it is a good practice to learn from the work of others. Using a search engine to check how other authors use certain expressions may help a lot.

  • False friends, idioms and other idiomatic expressions
  • Watch out for false friends. No matter how proficient you are in a foreign language you cannot help falling from time to time in the trap of the so called "false friends", words that look similar in two languages but whose meanings or uses might be completely different.

    Try to avoid idioms as much as possible. "Idioms" are expressions that may convey a completely different meaning from what their individual words seem to mean. Sometimes, idioms are difficult to understand even for native speakers!

  • Avoid slang, abbreviations, contractions...
  • Even though you are encouraged to use plain, everyday English, technical writing belongs to the formal register of the language.

    Try to avoid slang, unusual abbreviations that are difficult to understand and above all contractions that try to imitate the spoken language. Not to mention typical irc and family friendly expressions.

    17.1.2 Procedures

  • Test before write
  • It is important that authors test their examples before adding them to live-manual to ensure that everything works as described. Testing on a clean chroot or VM can be a good starting point. Besides, it would be ideal if the tests were then carried out on different machines with different hardware to spot possible problems that may arise.

  • Examples
  • When providing an example try to be as specific as you can. An example is, after all, just an example.

    It is often better to use a line that only applies to an specific case than using abstractions that may confuse your readers. In this case you can provide a brief explanation of the effects of the proposed example.

    There may be some exceptions when the example suggests using some potentially dangerous commands that, if misused, may cause data loss or other similar undesirable effects. In this case you should provide a thorough explanation of the possible side effects.

  • External links
  • Links to external sites should only be used when the information on those sites is crucial when it comes to understanding a special point. Even so, try to use links to external sites as sparsely as possible. Internet links are likely to change from time to time resulting in broken links and leaving your arguments in an incomplete state.

    Besides, people who read the manual offline will not have the chance to follow those links.

  • Avoid branding and things that violate the license under which the manual is published
  • Try to avoid branding as much as possible. Keep in mind that other downstream projects might make use of the documentation you write. So you are complicating things for them if you add certain specific material.

    live-manual is licensed under the GNU GPL. This has a number of implications that apply to the distribution of the material (of any kind, including copyrighted graphics or logos) that is published with it.

  • Write a first draft, revise, edit, improve, redo if necessary
  • - Brainstorm!. You need to organize your ideas first in a logical sequence of events.

    - Once you have somehow organized those ideas in your mind write a first draft.

    - Revise grammar, syntax and spelling.

    - Improve your statements and redo any part if necessary.

  • Chapters
  • Use the conventional numbering system for chapters and subtitles. e.g. 1, 1.1, 1.1.1, 1.1.2 ... 1.2, 1.2.1, 1.2.2 ... 2, 2.1 ... and so on. See markup below.

    If you have to enumerate a series of steps or stages in your description, you can also use ordinal numbers: First, second, third ... or First, Then, After that, Finally ... Alternatively you can use bulleted items.

  • Markup
  • And last but not least, live-manual uses SiSU to process the text files and produce a multiple format output. It is recommended to take a look at SiSU's manual to get familiar with its markup, or else type:

    $ sisu --help markup

    Here are some markup examples that may prove useful:

    - For emphasis/bold text:

    *{foo}* or !{foo}!

    produces: foo or foo. Use it to emphasize certain key words.

    - For italics:

    /{foo}/

    produces: foo. Use them e.g. for the names of debian packages.

    - For monospace:

    #{foo}#

    produces: foo. Use it e.g. for the names of commands. And also to highlight some key words or things like paths.

    - For code blocks:

    code{

      $ foo
      # bar

    }code

    produces:

    $ foo
    # bar

    Use code{ to open and }code to close the tags. It is important to remember to leave a space at the beginning of each line of code.

    17.2 Guidelines for translators

    This section deals with some general considerations to be taken into account when translating the contents of live-manual.

    As a general recommendation, translators should have read and understood the translation rules that apply to their specific languages. Usually, translation groups and mailing lists provide information on how to produce translated work that complies with Debian quality standards.

    Note: Translators should also read Contributing to this document. In particular the section Translation

    17.2.1 Translation hints

  • Comments
  • The role of the translator is to convey as faithfully as possible the meaning of words, sentences, paragraphs and texts as written by the original authors into their target language.

    So they should refrain from adding personal comments or extra bits of information of their own. If they want to add a comment for other translators working on the same documents, they can leave it in the space reserved for that. That is, the header of the strings in the po files preceded by a number sign #. Most graphical translation programs can automatically handle those types of comments.

  • TN, Translator's Note
  • It is perfectly acceptable however, to include a word or an expression in brackets in the translated text if, and only if, that makes the meaning of a difficult word or expression clearer to the reader. Inside the brackets the translator should make evident that the addition was theirs using the abbreviation "TN" or "Translator's Note".

  • Impersonal sentences
  • Documents written in English make an extensive use of the impersonal form "you". In some other languages that do not share this characteristic, this might give the false impression that the original texts are directly addressing the reader when they are actually not doing so. Translators must be aware of that fact and reflect it in their language as accurately as possible.

  • False friends
  • The trap of "false friends" explained before especially applies to translators. Double check the meaning of suspicious false friends if in doubt.

  • Markup
  • Translators working initially with pot files and later on with po files will find many markup features in the strings. They can translate the text anyway, as long as it is translatable, but it is extremely important that they use exactly the same markup as the original English version.

  • Code blocks
  • Some translators decide to include the code blocks in the translated files because it is easier for them to identify what has already been translated and what has not by looking at the percentages if they use a graphical translation program.

    Include the code blocks if you want to score a 100% complete translation.

    On the other hand some translators prefer to leave the code blocks "untranslated" (i.e. not including them). This makes the translation easier to maintain once finished because it does not require translators intervention if the code changes.

    Leave the code blocks empty (they will be automatically added then) if you want to make your translation easier to maintain.

  • Newlines
  • The translated texts need to have the exact same newlines as the original texts. Be careful to press the "Enter" key or type \n if they appear in the original files. These newlines often appear, for instance, in the code blocks.

    Make no mistake, this does not mean that the translated text needs to have the same length as the English version. That is nearly impossible.

  • Untranslatable strings
  • Translators should never translate:

    - The code names of releases

    - The names of programs

    - The commands given as examples

    - Metadata (often between colons :metadata:)

    - Links

    - Paths