Qué es TLDR y cómo usarlo explicado

Los usuarios de la línea de comandos de Linux deben estar familiarizados con el comando «man». Esto 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 muy útiles cuando 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 dirigido por la comunidad para mejorar las páginas man predeterminadas de Linux, proporciona documentación sencilla para cada comando o utilidad, y también demuestra el uso de comandos con ejemplos bastante simples. En este artículo, aprenderemos el proceso de instalación de 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 fácil de instalar TLDR es usar 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 primero deberán habilitar 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 su sistema CentOS para instalar Node y NPM.

sudo yum install nodejs npm

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 con TLDR es bastante simple, use el siguiente formato.

tldr Command

Donde reemplaza «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 manera extremadamente fácil y descriptiva? así es como se ve la documentación para el 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, proporciona una forma muy intuitiva de buscar información de pedidos. Muestra ejemplos de diferentes usos de cada comando, haciéndolos muy fáciles de entender.

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

$ tldr -l

contribuyente

Si no puede encontrar un pedido o no tiene más ejemplos de un pedido existente, puede contribuir al proyecto.

En primer lugar, asegúrese de seguir todos estos elementos:

Instrucciones

1. Lo mejor es limitar las páginas a unos 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 todo. hombre es para.
2. En caso de duda, elija el método seguro que sabe que siempre funcionará. Por ejemplo: Comandos que requieren sudo debe incluirlo directamente en los ejemplos.
3. Incluya opciones de letras además de las opciones de una sola letra. Esto le da al usuario la capacidad de entender 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 conceptos generales de UNIX, concéntrese solo en detalles de comandos específicos.

formato de descuento

El formato de cada página debe 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 hace cumplir 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 de símbolos

Usar {{simbólico}} sintaxis para los valores proporcionados por el usuario para permitir que los clientes tldr los resalten. Debes usar tokens de varias palabras serpiente_caso.

Instrucciones para elegir los nombres de los símbolos:

1. Los valores de los símbolos deben ser breves y descriptivos. P.ej: {{ruta_archivo}} 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: Usar detener -h {{5}} Que parada -h {{tiempo_en_HHmm}}
3. Para cualquier referencia a rutas de archivos o carpetas, utilice el formato {{camino a/}}. P.ej, ln -s {{ruta/al/archivo}} {{ruta/al/enlace simbólico}}. En el caso de una posible referencia tanto a un archivo como a una carpeta, utilice {{ruta/al/archivo_o_carpeta}}
4. Sigue {{camino a/}} cuando hay un comando relacionado con la ruta, a menos que la ubicación del archivo sea la predeterminada.
5. Si hay un comando que espera que un archivo tenga una cierta extensión, muéstrelo. Ejemplo: descomprimir x {{compressed_file.rar}}. Si se requiere una extensión genérica, use {{.ext}}

Estas son solo pautas, no reglas estrictas y rápidas, solo trate de seguirlas y haga que los ejemplos sean lo más intuitivos posible.

Enviar una solicitud de retiro

Puedes utilizar 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 arriba Aquí.

Línea de comando

1. Bifurcar el repositorio desde la interfaz de usuario de Github
2. Clona tu bifurcación 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. Confirmar los cambios

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

6. empujar a la bifurcación

    git push origin {{branch_name}}</>

7. Ve a la página de github de tu bifurcación y haz clic en el botón verde de solicitud.

Envíe solo cambios relacionados en la misma solicitud.

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

<command>: type of change

Ejemplo: ls: añadir página

También puede referirse a el almacén oficial para encontrar más documentación.

actualización TLDR

Es importante mantener actualizado el TLDR para tener la información más actualizada. Continuamente agrega más y más documentación y puede actualizarla usando el siguiente comando.

tldr --update

Uso en línea (en la web)

También puede ver la documentación/ayuda de comandos de Linux usando versión en línea. Los desarrolladores tienen una URL web que puede usar para buscar documentación o ayuda para cualquier utilidad/comando de Linux. Vaya a la siguiente URL y simplemente escriba el nombre del comando/utilidad que desea y presione «Enter», se le presentará la documentación de la comunidad sobre el comando que está buscando y es una interfaz bastante agradable.

Espero que les haya gustado este artículo, he 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 la productividad diaria de la línea de comandos de Linux. Le ahorra mucho tiempo y le brinda información muy necesaria de la manera más fácil y detallada posible. ¡Pruébalo hoy! háganos saber en la sección de comentarios acerca de su experiencia con esta utilidad.