Escribir un libro de programación: cómo presentar estructuras de directorios

Hago algo similar a su implementación ASCII, pero en lugar de un bloque ASCII, uso listas compactas con viñetas (con sublistas). Los nombres de archivos/directorios todavía tienen el estilo que tendrían en el texto continuo. Además de transmitir la estructura, esto también me brinda un lugar útil para agregar explicaciones donde sea necesario, lo cual es particularmente importante cuando (desde el punto de vista del usuario) la información es nueva. Por ejemplo, mi enfoque le permitiría explicar para qué sirve WEB-INF. (En esa viñeta: " WEB-INF: explicación." La tipografía distingue el nombre de la explicación.)

Las capturas de pantalla suelen ser una mala idea en mi experiencia; deben editarse/actualizarse por separado para que se pudran (como dijo @Piotr), y si el documento no es WYSIWIG sino, por ejemplo, HTML, es posible que el autor del documento no vea la captura de pantalla "en línea" durante la edición. No ver las capturas de pantalla en su (digamos) editor de texto puede provocar discrepancias entre el texto y la captura de pantalla. Además, las capturas de pantalla no son tan accesibles visualmente como el texto; no funcionan con lectores de pantalla (a menos que también escribas todo como texto alternativo) y los lectores no pueden cambiar el estilo de la página según el tamaño de fuente, los colores o el contraste. Esto no significa que nunca use capturas de pantalla u otros gráficos; son una parte importante de muchos documentos. lo hacesignifica no usarlos cuando no son necesarios. En este caso, tiene una alternativa de texto que proporciona la misma información, por lo que debe preferir eso.

Iría con la opción 2. Sin embargo, no necesita construir manualmente la estructura. En su lugar, recomiendo usar una herramienta como Tree , que debería manejar la impresión bonita como se muestra a continuación:

$ tree -d /var
var
|-- backups
|-- cache
|   |-- app-install
|   |-- apt
|   |   `-- archives
|   |       `-- partial
|   |-- apt-xapian-index
|   |   |-- index.1
|   |   `-- index.2
|   |-- cups
|   |   `-- rss
|   |-- debconf
|   |-- dictionaries-common
|   |-- flashplugin-installer
|   |-- fontconfig
|   |-- hald
|   |-- jockey
|   |-- ldconfig [error opening dir]
|   |-- man

El script debería estar disponible como paquete en su distribución. Puedo confirmar que está en Ubuntu.

También sugiero que se comunique con su editor para conocer su opinión. Es muy probable que el editor tenga sus propias pautas de estilo para tales asuntos (teniendo en cuenta el diseño). Si continúa con una representación de texto, le recomiendo que agregue un adhesivo en algún lugar que le recuerde que debe verificar la sangría en el final: los espacios en blanco a menudo se desordenan cuando se presenta el libro.

PD... y su editor también preferirá una representación textual - ahorra tinta;)

Enfócate en tu objetivo principal:

Debe ser legible e intuitivo.

Los otros dos objetivos hacen tu vida más fácil, pero no necesariamente la vida de tus lectores. Tus lectores son lo primero.

Entonces, las capturas de pantalla de una estructura de directorio serían fáciles de comprender. Pero si tienes estrés y tienes que terminar el libro por alguna fecha límite, ¿qué sufrirá más? Sí, revisando las capturas de pantalla. ¿Siguen siendo correctos? ¿Se corresponden con el texto? ¿Es fácil perderse cosas importantes con prisa? Sí. Si fueran fáciles de cambiar, servirían mejor a sus lectores.

Verás, te engañé al principio, pero eso tenía un propósito: enfocar.

"Verse profesional" es un término extraño, muy usado en exceso, rara vez definido. Cuida el aspecto más tarde, o en el medio, pero no al principio, puedes cambiar las cosas.

Entonces, no te gusta

|-myproj
  |-WEB-INF
     |-classes
     |-libs

Entonces hazlo más simple. Qué pasa

-myproj
   -WEB-INF
      -classes
      -libs

Las estructuras de directorio son estructuras jerárquicas. Muestra la jerarquía y estarás bien. No haga demasiado hincapié en mostrar algunas líneas que apunten de padre a hijo, solo use sangría. Eso debería estar bien.

Pruebe tree -den la CLI. Hace más o menos lo que quiere, automáticamente y debería ser fácil de copiar y pegar en un documento.

shelelia@halo:~$ tree -d installs
installs
├── bash_library
├── dropbox
│   ├── DEBIAN
│   ├── DropboxServiceMenu-0.16.1
│   │   └── dropbox-scripts
│   └── kde
├── HP
...

Se ve mejor en un terminal que en esta publicación.

Wasabi ofrece dos enfoques (puedes encontrar ambos aquí )

ya sea con sangría

root/ # entry comments can be inline after a '#'
      # or on their own line, also after a '#'

  readme.md # a child of, 'root/', it's indented
            # under its parent. 

  usage.md  # indented syntax is nice for small projects
            # and short comments.

  src/          # directories MUST be identified with a '/'
    fileOne.txt # files don't need any notation
    fileTwo*    # '*' can identify executables
    fileThree@  # '@' can identify symlinks

o detallado

root/
  this is a comment on 'root'

root/readme.md
  comments are indented under their entry this
  comment is for 'readme.md', a child of 'root/'
  it's specified by the full path

root/usage.md
  the detailed syntax is good for large projects
  and comprehensive commenting

root/src/
  directories MUST be identified with a trailing '/'

root/src/file.txt # some file