Imprimiendo el Tutorial de Python en castellano

Hola!

Varias veces en el pasado Python Argentina editó en papel el Tutorial de Python en castellano, el cual tradujimos para mayor difusión en nuestro lenguaje.

Hoy el tutorial en castellano forma parte de toda la documentación de Python en castellano, y tiene toda una infraestructura para ayudar en la traducción, que se gestione como parte de la documentación oficial, etc.

Queremos volver a imprimir el Tutorial, para distribuirlo en escuelas, centros culturales, barrios, etc. Para ello se necesita:

  1. Generar PDFs a partir de la documentación oficial
  2. Que esos PDFs tengan sentido para ser impresos (hay muchos detalles que cuidar, como que tenga páginas en blanco para que los capítulos arranquen “del lado izquierdo”, un margen extra “del lado del abrochado” de cada página, etc.)
  3. Poner la plata para pagar la imprenta
  4. Gestionar la impresión

Necesitamos alguien que se haga cargo del punto 1, teniendo en cuenta que vamos a ayudar a esa persona para que termine quedando bien como para que cumpla el punto 2.

Ya hay un issue abierto sobre este tema en el proyecto de la documentación en castellano. Es un buen punto de arranque. El resto lo podemos coordinar por acá o por Telegram.

Los puntos 3 y 4 los cubrimos desde la Asociación Civil.

¿Quienes tienen ganas?

1 me gusta

Me sumo a colaborar! :muscle: :muscle:

¿Hay algún plazo estimado para tener todo listo?

No hay plazo. Lo primero que hacer sería generar un PDF, y ahí lo revisamos y anotamos todos los “detalles para que sea imprimible”, y de ahí laburamos… Gracias!

Perfecto.

Voy con lo del PDF y escribo por aquí en cuánto tenga novedades.

Saludos

pd: si alguien más se quiere sumar chifle y vemos cómo cuadrar voluntades!

Buenas! Hice un repaso de todo esto. En principio, visualizo dos opciones:

  • Con el repositorio de la documentación oficial, exportar los archivos LaTex del bloque del tutorial, modificar lo que nos parezca necesario y luego generar el .pdf.
    Se necesita cambiar ‘conf.py’, hacer un build local de la documentación y luego ejecutar
sphinx-build -j auto -W --keep-going -b latex -d cpython/Doc/build/doctree/tutorial -D language=es . tutorial_latex

Acá los archivos generados.

Con esos archivos pude armar este pdf similar al que está disponible en el sitio oficial.

  • Otra opción es tomar justamente ese PDF de la versión en español y trabajar directamente sobre tutorial.pdf. Supongo que podremos cambiar algunas cosas más o menos fácil pero debe limitar bastante las posibilidades.

¿Qué te parece mejor @facundo?
Abrazo

Va una pequeña actualización:

  • Me puse a tocar un poco el .tex y logré añadir el margen “del abrochado”.
  • Eliminaría del capitulo 14 en adelante. Osea el material terminaría con “¿Y ahora qué?”
  • Todos los capitulos terminan con “notas al pie” que, si no vi mal, están todas vacías. Así que borraría todo eso también.

Así quedó.

Entiendo que no es escalable hacer todos estos ajustes “manualmente” (aunque sean pequeñas correcciones en el archivo .tex). Por otro lado, no sé hasta qué punto realmente es necesario que salga directo listo para imprimir con nuevas versiones “y variaciones menores” del tutorial. ¿En las versiones anteriores cómo manejaron este tema?

Me gusta la idea de hacer una carátula con todos los nombres de quienes participaron de la traducción. Voy a investigar un poquito a ver si nos sale! :stuck_out_tongue:

Abrazo!

Hola!

Está muy bien! Sí, tal cual decís, hay que generar el PDF “casi final”, y no algo que hay que tocar mucho ya siendo PDF.

Algunos detalles a corregir:

  • hay que apuntar a un tamaño de hoja A5 (esto luego se ajusta un poco, pero siempre termina siendo más o menos de ese tamaño)

  • la carátula es otra, pero eso NO IMPORTA (porque se maneja por separado)

  • los márgenes son pocos, aumentar la distancia al borde de la hoja

  • tiene que ser blanco y negro (así tenemos menos sorpresas cuando efectivamente se imprima en blanco y negro); sí, el “coloreado de sintaxis” queda en tonos de grises, pero bueno, es MUY caro imprimir todo a color

  • sacar las “Notas al pie” vacias

  • hay forma de sacar las “cajas de recuadro” alrededor de los códigos?

  • (esto creo que es más a nivel traducción) los códigos que están cortados dicen “continué en la próxima página” y “proviene de la página anterior”; estas dos frases deberían ser consistentes en tiempo y sujeto

  • habiendo dicho eso, habría que probar cómo queda todo SIN cortar los códigos por la mitad, porque es medio imposible “seguir la indentación” de una página a la otra…

  • todo lo que son títulos que son “Documentación de Python en Español, Versión 3.10.0” deberían ser “Tutorial de Python 3.10”

  • el código en la caja última al final de la página 31 está mal

  • del capítulo 14 para adelante hay que sacarlo… sacar las páginas en sí es muy fácil, el tema es cómo sacarlas del índice…

Tené en cuenta que no hace falta dejar “algo listo para que siempre salgan impresos”. Quizás lo mejor es anotar los pasos o las correcciones, pero no tiene que ser automático… Pero lo que sí no escala es toquetar mucho los .tex porque si querés generar todo de nuevo antes de traducir perdés lo hecho…

Gracias!

Va de nuevo con algunos comentarios:

  • Me armé un repositorio con el paso a paso. Ahí mismo metí el nuevo pdf. Si te parece, una vez que lo tengamos listo y algo más prolijo volcamos el contentido en pyar/tutorial o dónde sea mejor.
  • Tamaño A5 [x]
  • Aumentar márgenes [x] (de un sólo lado 20mm adicionales a los que vienen por defecto)
  • Respecto a los colores: por ahora lo hice de una manera muy “punga”: comenté las lineas que setean los distintos colores y como consecuencia queda todo en negro. (bah, casi todo, me quedaron colgados los títulos y el índice). Debería investigar un cacho más…
  • Sacar las “notas al pie” vacías [x]
  • Sacar “cajas de recuadro” [x]
  • Arreglar frases respecto a códigos cortados [x]
  • Arreglar títulos [x]
  • Quitar capitulo 14 y ss. + arreglar índice [x]

Pendiente:

  • Carátula
  • Probar cómo queda SIN cortar los códigos a la mitad. Idem “colores”. Debería indagar un poco más en LaTex para ver cómo configurarlo. A simple viste no lo encontré.
  • el código en la caja última al final de la página 31 está mal: No me doy cuenta a qué código te referís. Corrí el ejemplo y el resultado era tal cuál estaba ahí. ¿o le estoy pifiando al ejemplo problemático?
  • Reemplazaría el texto que viene a continuación del índice y antes del capitulo 1 por algo con más “punch”. O por lo menos sacar la última la oración: “Es interesante leer el Glosario”. Tristisimo el cierre :stuck_out_tongue: jaj

Abrazo y buena semana!

¡¡¡Está mucho mejor!!! Que buenísimo.

Veamos los pendientes que anotaste, más alguna cosita nueva:

  • Carátula: olvidate, esto es re-custom, y a color. Es algo que habría que hacer en paralelo, pero estaría bueno anotar acá toda la info que tendríamos que incluir…

  • Colores: en el intento de sacar los colores, quedó sin syntax highlighting :(. Esto lo debemos mantener (pero en tonos de grises, porque se va a imprimir en B&N).

  • No cortar código. Probémoslo… la situación actual donde quedan lineas de un lado y del otro es bastante poco pedagógico.

  • Código malo: ahora no está más en la página esa, claro. Es al final de “Ejemplos de funciones”, esto:

def foo(name, /, **kwds):
    return 'name' in kwds
>>> foo(1, **{'name': 2})
True

Fijate que es como que le falta el >>> a la definición de la función…

  • Intro (eso que está entre el índice y el cap 1): sí, hay que “tunearlo”, fijate que también habla de otra documentación, lo que tiene sentido si podés hacer click y verla, pero para lo escrito, no creo que tenga sentido ponerlo en un texto tan “de presentación”

  • tamaño de letra: tenemos que trabajar con esto, ahora que la hoja es más chica. Fijate como quedó la página 165 (donde arranca 11.3), el título queda muy largo, y el código es totalmente ilegible. Para probar, le bajaría un punto al título y a la letra normal, y dos puntitos al monospaced.

¡Sigamos mejorándolo! Gracias :slight_smile:

Aquí de nuevo el pdf. :slight_smile:

  • Carátula: OK.
  • Colores: encontré el modo de pasar todo a escala de grises. No me gusta que el índice como tiene hipervínculos queda de color gris… pero será cosa de quitar los links y ya (o cambiar el color a los links). :muscle: :muscle:
  • No cortar el código: la buena es que logré ajustar editando un parámetro medio recóndito jej! la mala es que si un bloque excede el tamaño de la página completa “no pasa a la siguiente página”. Para que se entienda mejor: ver en la página 77 (83 del pdf) (es la sección de la función dir()). Es el único caso que tenemos, y la verdad que el contenido del bloque de código no me parece muy importante. Podríamos achicar el margen del lado derecho a todo el pdf y probablemente ganemos un par de lineas y se arregla. O directamente cortar ese código y poner un “etc”. ¿Qué decís?
  • Código malo: OK. Ahora lo vi.
  • Retoqué el texto de la intro. Fijate por favor qué te parece.
  • Tamaño de la letra: Lo resolví añadiendo Scale=0.9 en el archivo principal donde se definen los tres tipos de letras. Adicionalmente, achiqué el texto que corresponde a los bloques de código. En contra de mi intuición me resultó bastante dificil dar con la manera de agrandar exclusivamente el título o la letra normal.
    Por otro lado, simplifiqué el texto que aparece en el pie de página con el nombre del capitulo y demás porque en algunas páginas era muy largo y se superponía con el número de página.

La seguimos! Abrazo

He vuelto! :sunglasses:

  • Quité el coloreado en los links y ahora el índice se ve mejor.
  • Cambié los margenes (20 mm del lado del “anillado” y 10 mm del otro). Esto hace que se corrija el problema que veíamos en la sección 6.3 dir() (página 73 / 79 del pdf).

El paso a paso lo dejé actualizado acá.

El link al pdf sigue siendo el mismo.

Ahora sí me convence… ¿me pongo en campaña para encontrar a alguien que nos de una mano con la carátula? ¿qué decís?

Abrazo

Hola! Todo lo que veo lo veo muy bien. Pero no encuentro el índice en ese PDF…

Dale, metámosle con la carátula y con la página de “todes les traductores”…

1 me gusta

:+1: :+1: :+1:
Me quedó colgado un pdf viejo. Ya subí el correcto.