¿Qué es TLDR y cómo se utiliza?

Los usuarios de la línea de comandos de Linux deben estar familiarizados con el comando «man». Significa páginas de manual, lo que significa que cada comando o utilidad de Linux viene con el conjunto de instrucciones o el posible uso del comando. Las páginas de manual son de gran ayuda mientras se trabaja en la línea de comandos, pero a menudo, la documentación disponible a través de las páginas de manual es demasiado larga o confusa para aprender. Tampoco proporciona ningún ejemplo de la vida real. Todo lo que incluye son los detalles de lo que hace ese comando en particular y cuáles son sus interruptores disponibles (también llamados opciones).

TLDR (Too Long Didn’t Read) es un esfuerzo impulsado por la comunidad para mejorar las páginas de manual de Linux predeterminadas, proporciona una documentación fácil de usar para cada comando o utilidad y también demuestra el uso del comando con ejemplos bastante simples. En este artículo, aprenderemos el proceso para instalar TLDR y cómo usarlo para que funcione mejor en terminales Linux.

Cómo instalar TLDR en sistemas Ubuntu y CentOS

La forma más sencilla de instalar TLDR es mediante NPM y Nodejs. Entonces, primero debemos instalar estos dos componentes en nuestro sistema. Los usuarios del sistema Ubuntu pueden instalar NPM y Nodejs usando el siguiente comando.

sudo apt-get install nodejs npm

Los usuarios de CentOS deberán habilitar primero el repositorio EPEL de Yum. Ejecute el siguiente comando para instalar el repositorio de Epel, una vez que esté activo, podremos instalar nodejs y npm usando YUM.

yum install epel-release -y

Ejecute el siguiente comando en el sistema CentOS para instalar Node y NPM.

sudo yum install nodejs npm

Muy bien, ejecute el siguiente comando en su sistema ahora para completar el proceso de instalación.

sudo npm install -g tldr

Felicitaciones, ha equipado con éxito su sistema Linux con manuales de comandos fáciles de entender.

Ejemplos de TLDR

La sintaxis para obtener ayuda para usar TLDR es bastante simple, use el siguiente formato.

tldr Command

Donde reemplace «Comando» con la utilidad real o el nombre del comando para el que está tratando de obtener documentación.

La documentación para el comando «ls» se ve como se muestra a continuación.

# tldr ls

ls
List directory contents.

- List files one per line:
ls -1

- List all files, including hidden files:
ls -a

- Long format list (permissions, ownership, size and modification date) of all files:
ls -la

- Long format list with size displayed using human readable units (KB, MB, GB):
ls -lh

- Long format list sorted by size (descending):
ls -lS

¿No es una forma extremadamente fácil y descriptiva? así es como se ve la documentación del comando tar:

# tldr tar

tar
Archiving utility.
Optional compression with gzip / bzip.

- Create an archive from files:
tar cf target.tar file1 file2 file3

- Create a gzipped archive:
tar czf target.tar.gz file1 file2 file3

- Extract an archive in a target folder:
tar xf source.tar -C folder

- Extract a gzipped archive in the current directory:
tar xzf source.tar.gz

- Extract a bzipped archive in the current directory:
tar xjf source.tar.bz2

- Create a compressed archive, using archive suffix to determine the compression program:
tar caf target.tar.xz file1 file2 file3

Como puede ver, ofrece una forma muy intuitiva de buscar información sobre comandos. Muestra ejemplos de los diferentes usos de cada comando, lo que los hace muy fáciles de entender.

También puede enumerar todos los comandos disponibles en el repositorio escribiendo:

$ tldr -l

Contribuyendo

Si no encuentra un comando o tiene más ejemplos de un comando existente, ¡puede contribuir al proyecto!

En primer lugar y muy importante, asegúrese de respetar todos estos elementos:

Pautas

1. Es mejor mantener las páginas en alrededor de 5 ejemplos. Si es realmente necesario, las páginas pueden ser más largas, pero no pueden exceder los 8 ejemplos. La página no tiene que cubrir todo, eso es lo que hombre es para.
2. Cuando tenga dudas sobre algo, opte por el método seguro que sabe que siempre funcionará. Por ejemplo: comandos que requieren sudo debe incluirlo directamente en los ejemplos.
3. Incluya opciones deletreadas además de las opciones de una sola letra. Esto le da la posibilidad al usuario de comprender lo que está haciendo.
4. En los ejemplos, comience con las opciones más fáciles y luego continúe con las más complejas.
5. Evite explicar los conceptos generales de UNIX, céntrese únicamente en los detalles específicos de los comandos.

Formato de rebajas

El formato de cada página debería ser así:

# command-name

> Short, snappy description.
> Preferably one line; two are acceptable if necessary.

- Example description:

`command -opt1 -opt2 -arg1 {{arg_value}}`

- Example description:

`command -opt1 -opt2`

Hay un formateador que aplica el formato anterior. Se ejecuta automáticamente en cada solicitud de extracción, pero puede instalarlo para ver cómo se verán sus contribuciones:

$ sudo npm install tldr-lint
$ tldrl -f {{page.md}}

Puedes consultar más usos o tldrl escribiendo:

$ tldr tldrl

Sintaxis del token

Usar {{simbólico}} sintaxis de los valores proporcionados por el usuario para permitir que los clientes tldr los resalten. Los tokens de varias palabras deben usarse caso_serpiente.

Pautas para elegir nombres de tokens:

1. Los valores de los tokens deben ser breves y descriptivos. Por ejemplo: {{file_route}} o {{inicio / usuario / .bashrc}}
2. Si el ejemplo es más claro usando un valor real en lugar de escribir la variable de entrada, el nombre del parámetro o lo que sea, use el valor real. Por ejemplo: use apagado -h {{5}} más bien que apagar -h {{time_in_HHmm}}
3. Para cualquier referencia a rutas a archivos o carpetas, use el formato {{ruta / a / }}. Por ejemplo, ln -s {{ruta / al / archivo}} {{ruta / al / enlace simbólico}}. En caso de una posible referencia tanto a un archivo como a una carpeta, utilice {{ruta / a / archivo_o_carpeta}}
4. Siga el {{ruta / a / }} convención cuando hay un comando relacionado con la ruta, excepto cuando la ubicación del archivo es implícita.
5. Si hay un comando que espera que un archivo tenga una extensión específica, muéstrelo. Ejemplo: unrar x {{archivo_comprimido.rar}}. Si se necesita una extensión genérica, use {{.ext}}

Estas son solo pautas, no reglas estrictas, solo intente seguirlas y hacer que los ejemplos sean lo más intuitivos posible.

Enviar una solicitud de extracción

Puedes usar el método que prefieras:

Interfaz web de Github

La forma más sencilla es editar la página directamente desde la interfaz de usuario de Github. Puedes ver algunas instrucciones sobre aquí.

Línea de comando

1. Bifurcar el repositorio desde la interfaz de usuario de Github
2. Clona tu fork en tu computadora local

   https://help.github.com/articles/editing-files-in-another-user-s-repository/

3. Crear una rama de características

   git checkout -b {{branch_name}}

4. Haz tus cambios
5. Confirma los cambios

    git commit --all -m "{{commit_message}}"</>

6. Empuja hacia tu tenedor

    git push origin {{branch_name}}</>

7. Vaya a la página de github de su bifurcación y haga clic en el botón verde de solicitud de extracción.

Envíe solo los cambios relacionados en la misma solicitud.

Para el mensaje de confirmación, use este comando:

<command>: type of change

Ejemplo: ls: agregar página

También puede consultar el repositorio oficial para encontrar más documentación.

Actualización de TLDR

Es importante mantener el TLDR actualizado para que pueda tener disponible la información más actualizada. Continuamente está agregando más y más documentación y puede actualizarlo usando el siguiente comando.

tldr --update

Uso en línea (basado en web)

También puede ver la documentación / ayuda para el comando de Linux usando el versión en línea. Los desarrolladores tienen una URL web que puede usar para buscar la documentación o ayuda para cualquier utilidad / comando de Linux. Dirígete a la siguiente URL y simplemente escribe el nombre de la utilidad / comando que desees y presiona «Enter», se te presentará la documentación de la comunidad del comando buscado y es una interfaz bastante atractiva.

Espero que haya disfrutado de este artículo, hemos discutido el proceso de instalación y uso del comando TLDR en este tutorial. También puede utilizar la versión en línea de esta utilidad para mejorar su productividad diaria de trabajo en la línea de comandos de Linux. Le ahorra mucho tiempo y le proporciona la información que tanto necesita de la manera más fácil y detallada posible. ¡Pruébalo hoy! Háganos saber en la sección de comentarios sobre su experiencia con esta utilidad.