Make -R the default in the CLI

[alshain]

I realize changing defaults is a dangerous road, but I'm a big believer in things should "just work".

However, considering asciidoctorj "**/*.adoc -D build" will output all files into the same directory structure, relative links to images, other articles etc will all stop working unless the author deliberately places the files into directories but wrote all links as if the adoc files were inside the same directory.

I had only discovered that files in subdirectories weren't processed "properly" (i.e. as expected) after our documentation grew into actually using subfolders.

Thoughts?

[abelsromero]

For building whole directories, specially if you want to process resources and ensure the target directory contains everything, I recommend using a build tool which better covers such use cases. If you are feel more comfortable in Java you can use the maven-plugin or the gradle-plugin.

[mojavelinux]

Though, to @alshain's point, this is supported in the Ruby version of the CLI: asciidoctor/asciidoctor#1394 (comment). It's not (and should not be) the default. You do have to specify it for reasons I cited in that comment.

Currently, -R isn't supported by the asciidoctorj command as far as I can tell. If it were, the command would be:

asciidoctorj -R . "**/*.adoc -D build

I agree with @abelsromero that are limits to what the CLI can and should handle and you should consider a build tool once you cross that limit.

[alshain]

It will be supported in the next release in asciidoctorj as well: #818

I just think the default should do what the user expects. A user does not expect that the glob will find files in subdirectories but not preserve the folder structure. What's the benefit of having asciidoctorj do that by default if the user specifies a glob and an output directory?

[mojavelinux]

It's not the default because we don't all agree on what the user expects. As I pointed out, you need to be explicit. And, frankly, that's a good thing.

[mojavelinux]

If you feel very strongly there is another path forward you'll need to:

1. work upstream in Asciidoctor Ruby (since AsciidoctorJ needs to stay in alignment with Asciidoctor Ruby)
2. propose a flag that would flatten the output
3. implement the changes and test them

;)

[mojavelinux]

I added some docs to the user manual about the -R flag.

https://asciidoctor.org/docs/user-manual/#process-multiple-source-files-from-the-cli (see end of section)

As I was writing those docs, it did occur to me that using -D and not using -D in some respects produces different results. Having thought about it more, I am more open to the idea. But we still need some sort of "flatten" flag so that the existing behavior can still be achieved. (Look for other tools that have a similar behavior so we can build on conventions).

My offer still stands.

[mojavelinux]

zip uses --junk-paths. yarn uses --flat. I'm thinking perhaps --flatten-path (or --flatten-paths) or just --flatten. rsync uses --no-R (which is a strange convention).

[robertpanzer]

I think it's safe to close this ticket.
-R is a supported option now, and a user can set it when needing it.