search

asciidoctor / asciidoctor-extensions-lab

A lab for testing and demonstrating Asciidoctor extensions. Please do not use this code in production. If you want to use one of these extensions in your application, create a new project, import the code, and distribute it as a RubyGem. You can then request to make it a top-level project under the Asciidoctor organization.
Other
104 stars 101 forks source link

Idea: Create file tree containing all included files #125

Closed LoSong closed 3 years ago

LoSong commented 3 years ago

Currently, I'm working on an AsciiDoc project containing lots of .adoc files combined through interlinked "include" directives to make it as flexible as possible for editing and composability, e.g.:

index.adoc
|___ ../../path/a/file1.adoc
|___ ../../path/b/file2.adoc
     |___ ../path/c/file3.adoc
|___ ../../path/d/file4.adoc
|___ file5.adoc
     |___ ../path/e/file6.adoc
     |___ ../../path/f/file7.adoc
|___ file8.adoc

So, for example, index.adoc includes file5.adoc includes file6.adoc.

The problem is that due to multiple includes from multiple paths and folders the document structure will become confusing very rapidly, at least for people not familiar with AsciiDoc (or mark-up concepts in general).

So my idea is to use a preprocessor that creates a file tree from all files included during the generating process.

There seem to be at least two possible approaches:

Enhancement of the include directive

When preprocessing includes (and merging the content), the preprocessor simultaneously collects paths, folders and filenames and generates the file tree (either in a separate file or as additional comment in the root .adoc file, i.e. index.adoc in the example given above).

Additional preprocessor

Working exactly like the include preprocessor, but without merging the file content, only collecting paths, folders and filenames of the included files (again either in a separate file or as comment in the root .adoc file).

I would prefer the comment solution because then the writer can see the connections directly without the need to open another file.

I see at least two options for presenting the paths::

1) Relative paths to root .adoc file 2) Absolute path (maybe reduced to the differing part in a second step)

The result could look like the example above.

BTW: Maybe it is possible to generalise it and just look for any kind of used relative/absolute paths in the content. So it would be possible not only to create a file tree but additionally an image tree (with the used images dispersed across paths and folders).

This is not intended to be a "table of images", but assistance for the writer/editor (as it is with the file tree).

So long, LoSong

mojavelinux commented 3 years ago

While I welcome this idea, please understand that this repository is not for proposing new features. This is a place to share code ideas that have already been developed (or are in active development) with the community, but that don't fit in another project. If you're planning to develop this idea further, you can follow-up with a PR. But it would really be better if you pushed the code to a dedicated repository and shared a link to it.

LoSong commented 3 years ago

Hello Dan, thanks for clarification and sorry for the inconvenience.

Unfortunately, I'm a writer, not a developer/programmer. So I don't have any code to share yet.

I've created an empty repository for this idea and opened an issue for this: https://github.com/LoSong/asciidoctor-extension-filetree/issues/1

So further discussion could take place over there. And maybe there will be some code to share in the future.

Best regards