A solicitud de El Mau

Reviewed-on: elmau/libreoffice-books#1

.gitignore

@@ -1,3 +1,6 @@
+*.geany
+book/
+
 # ---> Python
 # Byte-compiled / optimized / DLL files
 __pycache__/

CHANGELOG

@@ -0,0 +1,5 @@
+v 0.2.0 [18-oct-2021]
+    - Conceptos iniciales
+
+v 0.1.0 [18-sep-2021]
+    - Introducción a Basic

CONTRIBUTING.md

@@ -0,0 +1,26 @@
+## For translate
+
+* Clone this repository.
+* Make a new branch from `develop`:
+
+    `git switch -c new_language develop`
+
+* Add new directory inside `source` with the new language name
+* Copy folder `src` from `/source/es/LibreOffice_Macros_con_Basic/src` to new language directory.
+* Translate files, not change de files names.
+* Push your changes and branch to your repository.
+* Make a  Pull Request (PR) from your branch to own branch **develop**.
+
+
+## Para traducir.
+
+* Clona este repositorio.
+* Crea una nueva rama a partir de la rama `develop`.
+
+    `git switch -c nuevo_idioma develop`
+
+* Agrega un nuevo directorio dentro del directorio `source` con el nombre del nuevo lenguaje.
+* Copia el directorio `src` en `/source/es/LibreOffice_Macros_con_Basic/src` dentro del directorio del nuevo lenguaje.
+* Traduce los archivos, no cambies los nombres de los archivos.
+* Empuja tu rama y tu cambios a tu propio repositorio.
+* Crea un nuevo Pull Request (PR) desde tu rama hacia nuestro repositorio siempre a la rama `develop`.

README.md

@@ -1,3 +1,9 @@
 # libreoffice-books
 
-Books for LibreOffice
+Books for LibreOffice
+
+[LibreOffice Macros con Basic][1]
+
+
+
+[1]: https://doc.cuates.net/libobasic/

VERSION

@@ -0,0 +1 @@
+LibreOffice Macros con Basic v0.2.0

source/es/LibreOffice_Macros_con_Basic/book.toml

@@ -0,0 +1,16 @@
+[book]
+authors = ["Mauricio Baeza"]
+language = "es"
+multilingual = false
+title = "LibreOffice Macros con Basic"
+
+[build]
+create-missing = false
+
+[output.html]
+default-theme = "light"
+preferred-dark-theme = "navy"
+additional-css = ["css/custom.css"]
+additional-js = ["highlight.js"]
+git-repository-url = "https://git.cuates.net/elmau/libreoffice-books"
+git-repository-icon = "fa-git"

source/es/LibreOffice_Macros_con_Basic/css/custom.css

@@ -0,0 +1,5 @@
+
+.author_cite{
+    font-weight: bold;
+    float: right;
+}

source/es/LibreOffice_Macros_con_Basic/src/00_portada.md

@@ -0,0 +1,22 @@
+# Portada
+
+
+![Logo LibreOffice](img/000_macros.png)
+
+Desarrollo de macros con Basic en LibreOffice
+
+* **Autor**: Mauricio Baeza
+* **Cuidado de la edición**: Celia Palacios
+
+
+### Licencia:
+
+Texto bajo los términos de la [GNU Free Documentation License][1] versión 1.3 o posterior o la [Creative Commons Attribution License][2], versión 4.0 o posterior.
+
+Código del libro bajo la [GNU General Public License][3] versión 3 o posterior.
+
+
+
+[1]: https://www.gnu.org/licenses/licenses.html#FDL
+[2]: https://creativecommons.org/licenses/by-sa/4.0/
+[3]: https://www.gnu.org/licenses/gpl-3.0.html

source/es/LibreOffice_Macros_con_Basic/src/01_Introduccion.md

@@ -0,0 +1,45 @@
+# Introducción
+
+> "Quien recibe una idea de mí, recibe instrucción sin disminuir la mía; igual que quien enciende su vela con la mía, recibe luz sin que yo quede a oscuras."
+
+<div class="author_cite">Thomas Jefferson</div>
+<br><br>
+
+Este libro es la revisión completa de mi anterior libro ["Aprendiendo OOo Basic"][1], el cual estaba orientado al (casi) difunto Apache OpenOffice. Ahora, ha sido reescrito y orientado completamente a [LibreOffice][2].
+
+El propósito de este libro es el mismo del anterior: ayudarte a que tu curva de aprendizaje sea menos pronunciada que la mía. Ahora cuento con un poco más de experiencia en el tema y es mi deseo que se vea reflejada en él.
+
+La documentación en nuestro idioma no es precisamente abundante. Hacen falta manos para generar documentación de calidad en diferentes estilos para diferentes públicos y niveles. Si cuentas con experiencia en los temas de este libro, puedes ayudar a ampliarlos. También puedes ponerte en contacto conmigo si requieres alguna orientación.
+
+La versión de LibreOffice usada para escribir este libro es la más reciente (en este momento es la 7.2). Siempre asegúrate de descargar el programa **únicamente** desde el [sitio oficial][2].
+
+Mi distribución de trabajo sigue siendo [ArchLinux][3] con Gnome como escritorio. Esto solo es relevante para las capturas de pantalla. LibreOffice es cada vez más personalizable, así que aquellas pueden variar dependiendo del sistema operativo (SO), distribución o escritorio que uses y de la personalización que tengas en tu equipo. Más adelante puedes ver algunas recomendaciones generales para trabajar.
+
+Este libro está en constante ampliación. El [repositorio del proyecto][4] debe ser siempre tu referencia para tener la última versión. Recuerda, si te parece que lo merece, habla de él, y si no, no seas chismoso. :)
+
+Los lugares donde puedes encontrarme para cualquier comentario o duda sobre este libro son:
+
+* El [grupo oficial de Telegram][5]
+* El [foro oficial][6]
+* En [Mastodon][7]
+
+**Importante, nunca respondo preguntas en privado** a menos que quieras contratar mis servicios. La duda que tengas, es bastante probable que otros la tengan, así que la pregunta y su respectiva respuesta deben ser públicas para que todos se beneficien.
+
+La tecnología avanza cada día. Mencionarlo puede ser obvio, pero aún no llega al usuario común, o sea, a nosotros, la tecnología que nos escriba nuestros programas por sí sola. Mientras llega, no queda otro camino que estudiar y practicar.
+
+Desarrollar macros es una tarea abstracta pero divertida; no hay atajos para llegar a dominar el tema, solo la practica, únicamente la práctica.
+
+Cada ejemplo mostrado en este libro ha sido probado al menos dos veces. Asegúrate de copiarlo correctamente: sí, puedes copiar.
+
+
+> Dedico este trabajo a las personas que me aman; sin su amor, no sería lo que soy.
+
+
+
+[1]: https://git.cuates.net/elmau/libreoffice-books/src/branch/master/books/es
+[2]: https://libreoffice.org
+[3]: https://archlinux.org
+[4]: https://git.cuates.net/elmau/libreoffice-books
+[5]: https://t.me/libreoffice_es
+[6]: https://ask.libreoffice.org/c/spanish/10
+[7]: https://mstdn.mx/@elmau

source/es/LibreOffice_Macros_con_Basic/src/02_Conceptos_iniciales.md

@@ -0,0 +1,269 @@
+# Conceptos iniciales
+
+Como soy una persona perezosa, no me gusta trabajar; por eso, cuando descubrí lo que se podía hacer con los lenguajes de programación, comprendí que esto es lo que necesitaba (y lo que me gustaba). Los lenguajes de programación nos permiten ordenar a la computadora que haga por nosotros esas tareas complejas, repetitivas y tediosas (y también las divertidas). Aquí aprenderemos cómo hacer en LibreOffice esas tareas complejas, repetitivas y tediosas mediante uno de los varios lenguajes con los que se puede programar en él: Basic.
+
+Las instrucciones que usamos para decirle al programa qué hacer, cómo, cuándo, en qué orden y con qué secuencia queremos que lo haga las llamaremos **macros**. Estas macros podemos crearlas de forma semiautomática con la **Grabadora de macros** (por ahora solo presente en Writer y Calc) o escribirlas nosotros desde cero. En mi opinión, a esta grabadora todavía le falta madurar un poco, por lo cual en este libro crearemos nuestras macros desde cero. Verás que no es tan complicado y sí muy divertido.
+
+
+## ¿Dónde se guardan las macros?
+
+Lo primero que tienes que aprender (y recordar) es que las macros se guardan en módulos, estos a su vez se guardan y organizan en bibliotecas, las cuales están contenidas dentro de documentos, como se indica en el siguiente diagrama, por cierto, hecho en Draw.
+
+![Diagrama conceptual de la organización de las macros](img/001_macros.png)
+
+Todos los documentos tienen una biblioteca especial predeterminada llamada **Standard**. A esta biblioteca le puedes agregar y eliminar módulos, pero no puedes eliminarla. Los módulos, además de macros, pueden contener **funciones** y los documentos también pueden contener **diálogos**.
+
+En la siguiente imagen puedes ver cómo se almacenan y organizan, dentro de un documento (codigo_libro.ods), una biblioteca creada por el usuario (mi_biblioteca), la biblioteca **Standard**, un módulo (mi_modulo) y dos macros.
+
+![Cómo se organizan y almacenan las macros en LibreOffice](img/002_macros.png)
+
+Las macros guardadas en documentos solo estarán disponibles mientras el documento esté abierto y si la opción **Seguridad de macros** está activada en algún nivel que coincida con el origen de confianza de nuestras macros. Por seguridad, solo activa macros de confianza, es decir, aquellas que sepas exactamente qué hacen o al menos quién la hizo.
+
+Las macros asimismo pueden guardarse en el perfil del usuario, con lo que estarán disponibles solo para este usuario. Estas son las que aparecen bajo **Mis macros** en la biblioteca **Standard** o en nuevas bibliotecas y modulos que puedes agregar.
+
+![Mis macros](img/003_macros.png)
+
+Finalmente, también las macros se pueden guardar dentro del directorio del programa LibreOffice, con lo que estarán disponibles para todos los usuarios. Solo un usuario con permisos de escritura en estos directorios, generalmente un administrador, puede guardarlas ahí. Todas las macros de ayuda y ejemplo que incorpora LibreOffice están en este espacio.
+
+![Macros de LibreOffice](img/004_macros.png)
+
+
+## Seguridad en macros
+
+Mencionamos que las macros, para poder ejecutarse, deben de estar activas. Dependiendo del nivel de seguridad establecido en LibreOffice, verás uno u otro mensaje o tal vez ninguno.
+
+De manera predeterminada, al instalar el programa, la opción **Seguridad de macros** está ajustada en el nivel de seguridad **Alto**, así que al abrir un documento con macros verás el siguiente mensaje, lo que indica que las macros estarán desactivadas.
+
+![Nivel de seguridad alto](img/005_macros.png)
+
+Mi recomendación es que establezcas el nivel de seguridad en **Medio**. Para esto, ve al menú **Herramientas > Opciones > LibreOffice > Seguridad > Seguridad de macros** o usa el atajo de teclado (también llamado método abreviado de teclado) Alt+F12. Al abrirse el diálogo **Seguridad de macros**, haz clic en la pestaña **Nivel de seguridad** y después en la opción **Medio**. Cierra los diálogos para guardar el nuevo valor pulsando los respectivos botones **Aceptar**.
+
+Ahora, al abrir un documento con macros, debes ver el siguiente diálogo, donde tendrás la opción de activar o desactivar las macros, según confíes o no en la fuente de origen.
+
+![Nivel de seguridad medio](img/006_macros.png)
+
+**IMPORTANTE**: Siempre verifica la fuente de tus macros. Ante la duda, es mejor que las desactives.
+
+
+## Mi primera macro
+
+Vamos a crear, paso a paso, nuestra primera macro. Abre Calc o tu aplicación LibreOffice favorita y guárdala en el lugar que quieras con el nombre que quieras. Te recomiendo usar una carpeta de trabajo exclusiva para los temas que veamos en este libro.
+
+Ve al menú **Herramientas > Macros > Organizar macros > Basic** y selecciona la biblioteca **Standard** del documento que hayas creado. Da clic en el botón **Nuevo**.
+
+![Organizar macros](img/007_macros.png)
+
+La acción anterior te permitirá establecer el nuevo nombre para un nuevo módulo. Escribe el nombre que quieras y da clic en el botón **Aceptar**.
+
+![Nuevo módulo](img/008_macros.png)
+
+Inmediatamente deberás ver el **entorno de desarrollo integrado** (EDI, de aquí en adelante) que incorpora LibreOffice para Basic.
+
+![Nuevo módulo en EDI](img/009_macros.png)
+
+Este EDI será nuestro centro de trabajo para todo, así que es muy importante te familiarices con él. Nota que al crear un nuevo módulo, el sistema agrega ya cierta información. Lo que ves ahí es la estructura más básica de una macro.
+
+```vbnet
+Sub Main
+
+End Sub
+```
+
+Reemplaza este contenido con el siguiente código:
+
+```vbnet
+Sub mi_primer_macro()
+    MsgBox "Podrido Mundo"
+End Sub
+```
+
+Vamos a **ejecutar la macro**, es decir, a pedirle que haga lo que hemos codificado que haga. Asegúrate de tener el cursor de escritura *dentro* de la macro. En este caso, en la línea con la palabra **MsgBox**. Presiona la tecla F5.
+
+Este debe ser el resultado:
+
+![Mi primera macro](img/010_macros.png)
+
+Si ves el resultado anterior, ¡felicidades! Ya eres todo un programador. Ya sabes el *cómo* pero, espera, no eres todavía un programador completo, te falta saber el *por qué*, para que logres lo que decía mi entrañable profesor de topografía:
+
+> El hombre teórico sabe el "por qué",
+> el hombre práctico sabe el "cómo";
+> lo ideal es saber "cómo" y "por qué"
+
+Para entender el *¿por qué?* analizaremos cada línea de nuestra primera macro en el siguiente tema.
+
+
+## Análisis de nuestra primera macro
+
+Toda macro tiene la estructura:
+
+```vbnet
+Sub nombre_de_la_macro()
+
+    REM Aquí va el código de la macro
+
+End Sub
+```
+
+Las palabras **Sub**, **REM** y **End Sub** son **palabras claves de Basic**. A las palabras claves también se les conoce como **palabras reservadas**, ya que solo el lenguaje de programación, en este caso Basic, puede hacer uso de ellas. Por ejemplo, *no puedes* escribir una macro como la siguiente:
+
+```vbnet
+Sub sub()
+
+    REM Aquí va el código de la macro
+
+End Sub
+```
+
+El código anterior, si intentas ejecutarlo, debe producirte un **error de ejecución**. Más adelante aprenderemos a controlar algunos tipos de errores.
+
+En la línea:
+
+```vbnet
+    MsgBox "Podrido Mundo"
+```
+
+Tenemos una nueva palabra clave de Basic: **MsgBox**, que al mismo tiempo es una **instrucción**, es decir, una palabra especial que el lenguaje, en conjunto con el EDI, reconoce de modo diferente y realiza, hace o ejecuta una tarea especifica. ¿Qué tarea? **MsgBox** muestra un *"mensaje"* en un cuadro de dialogo. ¿Qué mensaje? Como habrás notado (por que de aquí en adelante tendrás que ser muy observador), el mensaje que muestra es el que *nosotros* le indicamos delante de ella y, como este es una **cadena de texto**, lo tenemos que hacer entre comillas y separada de la instrucción por un espacio.
+
+¿Sucederá lo mismo con números? ¿Y con fechas o algún otro valor…?
+
+```vbnet
+    MsgBox 1234567890
+
+    MsgBox 15/01/1974
+
+    MsgBox 1dfgdfh245
+```
+
+Realiza todos las pruebas que quieras y me cuentas qué sucede.
+
+Observa la primer linea de la macro que acabas de hacer y que, si has seguido al pie de la letra, no tendrías que haber modificado:
+
+```vbnet
+    REM  *****  BASIC  *****
+```
+
+La primer palabra, **REM**, también es una palabra clave de Basic y lo que *hace* es decirle al programa (nuestra macro), que todo lo que hay frente a ella es un comentario. Es decir, el lenguaje de programación se lo saltara olímpicamente sin hacerle caso. Comentar las lineas de código es una practica ampliamente recomendada y útil, sobre todo cuando las macros van creciendo de tamaño y complejidad. Así que, asume esta recomendación *casi* como una regla: *siempre comenta tus líneas de código*.
+
+Por ahí he leído que un código bien escrito no necesitaba comentarios, pero como nosotros somos *novatos*, haremos caso omiso de ese comentario, pues como dijo alguna vez Ling Yu Tan, «Me gusta la gente *amateur*». Así que ve al código de nuestra macro y comenta la linea que le agregaste, de modo que te quede, así:
+
+```vbnet
+    REM Muestra un mensaje en un cuadro de diálogo
+    MsgBox "Podrido Mundo"
+```
+
+Los comentarios también puedes establecerlos con una comilla simple '.
+
+```vbnet
+    'Muestra un mensaje en un cuadro de diálogo
+    MsgBox "Podrido Mundo"
+```
+
+Además, podemos agregarlos al final de la linea de código:
+
+```vbnet
+    MsgBox "Podrido Mundo 1"  REM Muestra un mensaje de diálogo
+    MsgBox "Podrido Mundo 2"  'Muestra un mensaje de diálogo
+```
+
+Insisto, procura hacer comentarios sobre la mayor parte de tu código; tu memoria te lo agradecerá, así como todos los programadores con los que compartas tu código, si decides que sea software libre, como te recomiendo que sea.
+
+Entonces, recapitulando. Toda macro empieza con la palabra clave **Sub** y termina con las palabras claves **End Sub** y toda macro debe tener un nombre. Para nuestro ejemplo hemos usado: **mi_primero_macro**.
+
+Este nombre debe cumplir algunas sencillas reglas:
+
+1. No puede contener espacios.
+1. No puede iniciar con un número.
+1. No debe repetirse el nombre de la macro dentro del módulo donde se declara; o sea, no puede haber dos que se llamen igual en el mismo módulo.
+
+Si se viola esta última regla, al intentar ejecutar cualquiera de las dos, obtendrás el mensaje de error:
+
+![Mi primer macro](img/011_macros.png)
+
+Observa la primer línea del mensaje: **Error de sintaxis de BASIC**. Aquí, la palabra importante es **sintaxis** que, si nos atenemos a lo que dice la doña Real Academia Española, quiere decir:
+
+<dl>
+<dt>sintaxis</dt>
+
+<dd>(Del lat. *syntaxis*, y este del gr. σύνταξις, de συντάσσειν, coordinar).</dd>
+
+<dd>1. f. Gram. Parte de la gramática que enseña a coordinar y unir las palabras para formar las oraciones y expresar conceptos.</dd>
+
+<dd>2. f. Inform. Conjunto de reglas que definen las secuencias correctas de los elementos de un lenguaje de programación.</dd>
+</dl>
+
+De estas definiciones, la que nos interesa es la número dos. Trata de recordarla: *Conjunto de reglas que definen las secuencias correctas de los elementos de un lenguaje de programación*.
+
+A lo largo de este libro aprenderemos a implementar este conjunto de reglas, las cuales, te confesaré, no son tantas ni tan complejas y como seguro habrás notado, el EDI nos informa muchas veces cuando algo anda mal en la sintaxis.
+
+El EDI identificará cada línea de código a ejecutar de dos maneras: cuando encuentre un salto de línea o cuando existan dos puntos, como en el siguiente ejemplo:
+
+```vbnet
+    Sub sentencias_en_una_sola_linea()
+        MsgBox "Estas es una sentencia" : MsgBox "Esta es otra sentencia"
+    End Sub
+```
+
+En sentencias largas puedes usar el carácter de continuación de línea, que es el guion bajo, pero debes de recordar que es una sola sentencia:
+
+```vbnet
+    Sub sentencia_larga()
+        MsgBox "Esta es una línea larga de código, que se puede dividir " & _
+            "usando el guion bajo, como en este ejemplo"
+    End Sub
+```
+
+Basic no distingue mayúsculas de minúsculas en ninguna parte de su código, por lo que todas las formas siguientes son válidas sintácticamente:
+
+* Mezcladas mayúsculas y minúsculas
+
+```vbnet
+    Sub Mi_Primera_Macro()
+        MsgBox "Podrido Mundo"
+    End Sub
+```
+
+* Solo mayúsculas
+
+```vbnet
+    SUB MI_PRIMERA_MACRO()
+        MSGBOX "Podrido Mundo"
+    END SUB
+```
+
+* Solo minúsculas
+
+```vbnet
+    sub mi_primera_macro()
+        msgbox "Podrido Mundo"
+    end sub
+```
+
+En Basic es común la primera forma, pero en este libro usaremos una combinación de la primera para las palabras claves de Basic, y de la última para lo demás:
+
+```vbnet
+    Sub mi_primer_macro()
+        MsgBox "Podrido Mundo"
+    End Sub
+```
+
+
+## El EDI
+
+El entorno de desarrollo integrado (EDI) cuenta con algunas herramientas útiles mientras se escribe código. Para activarlas, sigue estos pasos:
+
+Ve al menú **Herramientas > Opciones > LibreOffice > Avanzado**. Activa la casilla de verificación **Activar funcionalidades experimentales**, acepta los cambios y reinicia LibreOffice.
+
+![Activar](img/012_macros.png)
+
+Regresa a **Herramientas > Opciones**. Debes ver una nueva rama debajo de **LibreOffice**, que se llama **EID de Basic**. Activa todas las casillas de verificación de esta sección.
+
+![EDI Basic](img/013_macros.png)
+
+Antes de aceptar los cambios, ve a **Herramientas > Opciones > LibreOffice > Tipos de letra**. En la sección **Configuración de tipos de letra para HTML, Basic y SQL** puedes establecer una mejor fuente para el editor de código y aumentar su tamaño si lo requieres. Los viejitos ya lo requerimos.
+
+![Tipo de letra](img/014_macros.png)
+
+Con esto ya estamos listos para iniciar nuestro camino en el aprendizaje de macros en LibreOffice, con este sencillo  lenguaje que es Basic. No existen atajos. Ni se logra en 21 días, como más de un libro por ahí lo “vende”, solo la practica diaria te dará la desenvoltura para escribir tus macros, así que practica mucho.
+
+
+¡Feliz programación!

source/es/LibreOffice_Macros_con_Basic/src/SUMMARY.md

@@ -0,0 +1,5 @@
+# Summary
+
+- [Portada](./00_portada.md)
+- [Introducción](./01_Introduccion.md)
+- [Conceptos iniciales](./02_Conceptos_iniciales.md)

source/es/LibreOffice_Macros_con_Python/book.toml

@@ -0,0 +1,16 @@
+[book]
+authors = ["Mauricio Baeza"]
+language = "es"
+multilingual = false
+title = "LibreOffice Macros con Basic"
+
+[build]
+create-missing = false
+
+[output.html]
+default-theme = "light"
+preferred-dark-theme = "navy"
+additional-css = ["css/custom.css"]
+additional-js = ["highlight.js"]
+git-repository-url = "https://git.cuates.net/elmau/libreoffice-books"
+git-repository-icon = "fa-git"

source/es/LibreOffice_Macros_con_Python/css/custom.css

@@ -0,0 +1,5 @@
+
+.author_cite{
+    font-weight: bold;
+    float: right;
+}

source/es/LibreOffice_Macros_con_Python/src/00_portada.md

@@ -0,0 +1,22 @@
+# Portada
+
+
+![Logo LibreOffice](img/000_macros.png)
+
+Desarrollo de macros en LibreOffice con Python
+
+* **Autor**: Mauricio Baeza
+* **Cuidado de la edición**: Celia Palacios
+
+
+### Licencia:
+
+Texto bajo los términos de la [GNU Free Documentation License][1] versión 1.3 o posterior o la [Creative Commons Attribution License][2], versión 4.0 o posterior.
+
+Código del libro bajo la [GNU General Public License][3] versión 3 o posterior.
+
+
+
+[1]: https://www.gnu.org/licenses/licenses.html#FDL
+[2]: https://creativecommons.org/licenses/by-sa/4.0/
+[3]: https://www.gnu.org/licenses/gpl-3.0.html

source/es/LibreOffice_Macros_con_Python/src/SUMMARY.md

@@ -0,0 +1,5 @@
+# Summary
+
+- [Portada](./00_portada.md)
+- [Introducción](./01_Introduccion.md)
+- [Conceptos iniciales](./02_Conceptos_iniciales.md)