Single CSS for multiple, nested adoc files

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
15 messages Options
Reply | Threaded
Open this post in threaded view
|

Single CSS for multiple, nested adoc files

ChrLipp
Hello all!

I have nested adoc files in different directories, like

- src/asciidoc
  - 1.adoc
  - 2.adoc
  - nested <dir>
    - 3.adoc

When I set the copycss flag I end in having an asciidoc.css in each directory.
When I set the linkcss flag and copy the css manually in the root of the output directory, the css-link of 3.adoc is wrong (it expects the css in the same directory).

Is there a solution for that?
Kind regards, CL
Reply | Threaded
Open this post in threaded view
|

Re: Single CSS for multiple, nested adoc files

LightGuardjp
besides rendering them in separate invocations? Um... you might be able to set an attribute in the document, can't think of the attribute name right now though. stylesheetdir? styledir?


On Tue, Sep 10, 2013 at 2:00 AM, ChrLipp [via Asciidoctor :: Discussion] <[hidden email]> wrote:
Hello all!

I have nested adoc files in different directories, like

- src/asciidoc
  - 1.adoc
  - 2.adoc
  - nested <dir>
    - 3.adoc

When I set the copycss flag I end in having an asciidoc.css in each directory.
When I set the linkcss flag and copy the css manually in the root of the output directory, the css-link of 3.adoc is wrong (it expects the css in the same directory).

Is there a solution for that?
Kind regards, CL


If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Single-CSS-for-multiple-nested-adoc-files-tp552.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML



--
Reply | Threaded
Open this post in threaded view
|

Re: Single CSS for multiple, nested adoc files

mojavelinux
Administrator
In reply to this post by ChrLipp
Hey Christian,

Great question. I hadn't considered this scenario, so I'm glad you brought it forward. I really had to give it some thought.

Solution A ::

The simplest solution, naturally, is to embed the stylesheet into the document. This happens in Asciidoctor 0.1.4 by default (no linkcss or copycss flags).

 $ asciidoctor '**/*.adoc'

Solution B ::

Another solution is to provide an absolute path to the stylesheet, assuming you are serving the documents from a webserver. In this case, you'd have to handle copying the stylesheet to where you want it manually.

 $ asciidoctor -a stylesdir=/stylesheets -a linkcss -a copycss! '**/*.adoc'

However, those solutions may not match your requirements. Here are some that might.

Solution C ::

When you are running Asciidoctor once across a nested set of documents, it's currently not possible to specify a single relative path for the stylesdir attribute that would work for all documents, since the relative depth differs for documents in subdirectories. One way to solve this problem, as Jason suggested, is to maintain the path to the stylesdir in each document.

For 1.adoc and 2.adoc, that would be:

:stylesdir: ./stylesheets

For 3.adoc, that would be:

:stylesdir: ../stylesheets

Now the handling of the stylesheet and the reference in the document will behave as you expect.

Solution D ::

This got me thinking, though, that perhaps Asciidoctor should set an implicit attribute that passes the relative path from the document to the top-level when processing documents that span subdirectories. I'm thinking something like `docrootdir`. That way, the stylesdir attribute in the document is portable to where the document is placed.

:stylesdir: {docrootdir}/stylesheets

What do you think about that idea and, if we pursue it, the proposed name of the attribute. This would be a feature that is specific to Asciidoctor's ability to process documents in subdirectories. We could also set the same attribute in the Maven and Gradle plugins.

-Dan


On Tue, Sep 10, 2013 at 1:59 AM, ChrLipp [via Asciidoctor :: Discussion] <[hidden email]> wrote:
Hello all!

I have nested adoc files in different directories, like

- src/asciidoc
  - 1.adoc
  - 2.adoc
  - nested <dir>
    - 3.adoc

When I set the copycss flag I end in having an asciidoc.css in each directory.
When I set the linkcss flag and copy the css manually in the root of the output directory, the css-link of 3.adoc is wrong (it expects the css in the same directory).

Is there a solution for that?
Kind regards, CL


If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Single-CSS-for-multiple-nested-adoc-files-tp552.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML



--
Reply | Threaded
Open this post in threaded view
|

Re: Single CSS for multiple, nested adoc files

ChrLipp
Hi Dan,

thanks for your feedback. I could live with duplicating (or multiplying) the css, I just wanted to learn if maybe there is a solution already there which I didn't notice.

Anyway, I would like to suggest another approach and you decide if you take any action:

Solution E ::

- Copy the CSS manually.
- Link to the stylesheet with stylesdir and linkcss
- Provide an additional flag like useRelativeCssLinking which takes the adoc path and the css path and tries to compute a relative path. If this is possible, use it. If not, stick to the absolute path.

Of course the path has to be converted to / directory seperators if it is a file path and used under windows. If under window that upper case / lower case handling might also be an issue.

I don't know Ruby, but in Java this is done with http://docs.oracle.com/javase/7/docs/api/java/nio/file/Path.html#relativize(java.nio.file.Path)

Solution F ::

Don't use nested dirs, put everything in the root dir :-)

What do you say?
Kind regards, Christian
Reply | Threaded
Open this post in threaded view
|

Re: Single CSS for multiple, nested adoc files

asotobu
In reply to this post by ChrLipp
Dan I think we need a way to handle this situation, for example in my talks about Asciidoctor, and when I teach personally to my mates how documentations should be written, I encourage them to create as many as adoc files as required and more important distribute them across their project as with code; so for example in src/main/resources/file1.adoc would contain the index file with includes to different files like src/main/resources/com/lordofthejars/foo/file2.adoc and so on, with this approach you know where to find exactly the documentation of a part of your project/module (at same place as normal resources of your project). Basically I try to give the same treatment of documentation as anything on a project.

Now because I am embedding CSS there is no problem, but of course as ChrLipp suggested it could be a problem in near future if people finds more useful to not embed CSS.

Reply | Threaded
Open this post in threaded view
|

Re: Single CSS for multiple, nested adoc files

LightGuardjp
It sounds to me like computing the relative path seems like the best long term solution. We'd need the doc root (which we should already have), the location of the file relative to the doc root and then the resources root directories (images, javascript, styles), of course we'd also need the output directories, but we should already have those as well.


On Thu, Sep 12, 2013 at 6:57 AM, asotobu [via Asciidoctor :: Discussion] <[hidden email]> wrote:
Dan I think we need a way to handle this situation, for example in my talks about Asciidoctor, and when I teach personally to my mates how documentations should be written, I encourage them to create as many as adoc files as required and more important distribute them across their project as with code; so for example in src/main/resources/file1.adoc would contain the index file with includes to different files like src/main/resources/com/lordofthejars/foo/file2.adoc and so on, with this approach you know where to find exactly the documentation of a part of your project/module (at same place as normal resources of your project). Basically I try to give the same treatment of documentation as anything on a project.

Now because I am embedding CSS there is no problem, but of course as ChrLipp suggested it could be a problem in near future if people finds more useful to not embed CSS.




If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Single-CSS-for-multiple-nested-adoc-files-tp552p577.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML



--
Reply | Threaded
Open this post in threaded view
|

Re: Single CSS for multiple, nested adoc files

asotobu
Yes it is a good solution, but we should be prepared for this kind of questions

El dijous 12 de setembre de 2013, LightGuardjp [via Asciidoctor :: Discussion] ha escrit:
It sounds to me like computing the relative path seems like the best long term solution. We'd need the doc root (which we should already have), the location of the file relative to the doc root and then the resources root directories (images, javascript, styles), of course we'd also need the output directories, but we should already have those as well.


On Thu, Sep 12, 2013 at 6:57 AM, asotobu [via Asciidoctor :: Discussion] <[hidden email]> wrote:
Dan I think we need a way to handle this situation, for example in my talks about Asciidoctor, and when I teach personally to my mates how documentations should be written, I encourage them to create as many as adoc files as required and more important distribute them across their project as with code; so for example in src/main/resources/file1.adoc would contain the index file with includes to different files like src/main/resources/com/lordofthejars/foo/file2.adoc and so on, with this approach you know where to find exactly the documentation of a part of your project/module (at same place as normal resources of your project). Basically I try to give the same treatment of documentation as anything on a project.

Now because I am embedding CSS there is no problem, but of course as ChrLipp suggested it could be a problem in near future if people finds more useful to not embed CSS.




If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Single-CSS-for-multiple-nested-adoc-files-tp552p577.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML



--



If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Single-CSS-for-multiple-nested-adoc-files-tp552p578.html
To unsubscribe from Single CSS for multiple, nested adoc files, click here.
NAML


--
Enviat amb Gmail Mobile
Reply | Threaded
Open this post in threaded view
|

Re: Single CSS for multiple, nested adoc files

LightGuardjp
Of course, however, I don't think we're ill-prepared for it currently. As Dan has stated we currently have four viable solutions (depending how automated you want to be and where you want the settings). Settling on a longer term solution that does what we need it to do, like the presented Solution E, completes the story:

We understand the problem. We currently have various workarounds and are discussing / implementing a more long term solution. For now, please consider one of the described workarounds...


On Thu, Sep 12, 2013 at 8:51 AM, asotobu [via Asciidoctor :: Discussion] <[hidden email]> wrote:
Yes it is a good solution, but we should be prepared for this kind of questions

El dijous 12 de setembre de 2013, LightGuardjp [via Asciidoctor :: Discussion] ha escrit:
It sounds to me like computing the relative path seems like the best long term solution. We'd need the doc root (which we should already have), the location of the file relative to the doc root and then the resources root directories (images, javascript, styles), of course we'd also need the output directories, but we should already have those as well.


On Thu, Sep 12, 2013 at 6:57 AM, asotobu [via Asciidoctor :: Discussion] <[hidden email]> wrote:
Dan I think we need a way to handle this situation, for example in my talks about Asciidoctor, and when I teach personally to my mates how documentations should be written, I encourage them to create as many as adoc files as required and more important distribute them across their project as with code; so for example in src/main/resources/file1.adoc would contain the index file with includes to different files like src/main/resources/com/lordofthejars/foo/file2.adoc and so on, with this approach you know where to find exactly the documentation of a part of your project/module (at same place as normal resources of your project). Basically I try to give the same treatment of documentation as anything on a project.

Now because I am embedding CSS there is no problem, but of course as ChrLipp suggested it could be a problem in near future if people finds more useful to not embed CSS.




If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Single-CSS-for-multiple-nested-adoc-files-tp552p577.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML



If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Single-CSS-for-multiple-nested-adoc-files-tp552p578.html
To unsubscribe from Single CSS for multiple, nested adoc files, click here.
NAML


--
Enviat amb Gmail Mobile



If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Single-CSS-for-multiple-nested-adoc-files-tp552p579.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML



--
Reply | Threaded
Open this post in threaded view
|

Re: Single CSS for multiple, nested adoc files

ChrLipp
I would like to make an addition to solution E:

When copycss is selected I would also copy it only once and then perform the linking to the copied css relatively for all files without any addional flag.

Kind regards, CL
Reply | Threaded
Open this post in threaded view
|

Re: Single CSS for multiple, nested adoc files

mojavelinux
Administrator
In reply to this post by ChrLipp
Christian,

I haven't thought through this issue thoroughly yet, but I want to contribute some information that should help advance things along in the meantime. Asciidoctor has a very robust, system-neutral path resolver built-in (named PathResolver). It can calculate absolute paths, jailed paths, relative paths and the like. It may need some enhancements to do direct relative calculations between two paths...the important point is that the foundation is there for chopping up and reassembling paths.

There are several utilities in Ruby for handling file path calculation, but in my experience they are all buggy in some way. That's why I wrote the PathResolver. So we're off to a good start there :)

-Dan


On Thu, Sep 12, 2013 at 1:54 AM, ChrLipp [via Asciidoctor :: Discussion] <[hidden email]> wrote:
Hi Dan,

thanks for your feedback. I could live with duplicating (or multiplying) the css, I just wanted to learn if maybe there is a solution already there which I didn't notice.

Anyway, I would like to suggest another approach and you decide if you take any action:

Solution E ::

- Copy the CSS manually.
- Link to the stylesheet with stylesdir and linkcss
- Provide an additional flag like useRelativeCssLinking which takes the adoc path and the css path and tries to compute a relative path. If this is possible, use it. If not, stick to the absolute path.

Of course the path has to be converted to / directory seperators if it is a file path and used under windows. If under window that upper case / lower case handling might also be an issue.

I don't know Ruby, but in Java this is done with http://docs.oracle.com/javase/7/docs/api/java/nio/file/Path.html#relativize(java.nio.file.Path)

Solution F ::

Don't use nested dirs, put everything in the root dir :-)

What do you say?
Kind regards, Christian


If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Single-CSS-for-multiple-nested-adoc-files-tp552p574.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML



--
Reply | Threaded
Open this post in threaded view
|

Re: Single CSS for multiple, nested adoc files

mojavelinux
Administrator
In reply to this post by asotobu
Alex,

We should be in good shape with include files as of 0.1.4. Include files are always calculated relative to the file that doing the including. That way, it's intuitive where it's looking. You can, of course, use an absolute include path by prefixing the path with an attribute reference that resolves to some root.

The main issue at stake here seems to be references in the output files to project-relative assets. The stylesheet is one example, but the same goes for JavaScript files and images too. It works fine when processing one file, or a group of files in the same directory. But once you start processing files in subdirectories under the same invocation of Asciidoctor, then the paths in stylesdir, imagesdir and scriptsdir is incorrect.

-Dan


On Thu, Sep 12, 2013 at 6:57 AM, asotobu [via Asciidoctor :: Discussion] <[hidden email]> wrote:
Dan I think we need a way to handle this situation, for example in my talks about Asciidoctor, and when I teach personally to my mates how documentations should be written, I encourage them to create as many as adoc files as required and more important distribute them across their project as with code; so for example in src/main/resources/file1.adoc would contain the index file with includes to different files like src/main/resources/com/lordofthejars/foo/file2.adoc and so on, with this approach you know where to find exactly the documentation of a part of your project/module (at same place as normal resources of your project). Basically I try to give the same treatment of documentation as anything on a project.

Now because I am embedding CSS there is no problem, but of course as ChrLipp suggested it could be a problem in near future if people finds more useful to not embed CSS.




If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Single-CSS-for-multiple-nested-adoc-files-tp552p577.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML



--
Reply | Threaded
Open this post in threaded view
|

Re: Single CSS for multiple, nested adoc files

mojavelinux
Administrator
In reply to this post by ChrLipp



On Thu, Sep 12, 2013 at 1:54 AM, ChrLipp [via Asciidoctor :: Discussion] <[hidden email]> wrote:

Solution E ::

- Copy the CSS manually.
- Link to the stylesheet with stylesdir and linkcss
- Provide an additional flag like useRelativeCssLinking which takes the adoc path and the css path and tries to compute a relative path. If this is possible, use it. If not, stick to the absolute path.

As I started to say in a previous response, the problem with something like useRelativeCssLinking is that this is not just an issue with CSS. The issue is with asset references in the output file.

I think we need to explore the following two solutions, and see which one plays out as most viable:

a. Provide a "docrootdir" attribute that can be used, perhaps in various ways, to keep the asset path consistent with the current directory level.
b. Recognize a relative directory for any attribute that ends with "dir" and adjust the value to reflect the current directory level

Instinct tells me that (b) is going to be very fragile and likely to confuse users that weren't on the design committee :) Although it seems like an extra step, using an attribute makes the intent very clear and gives us *lots* of room for doing smart things.

Now, we *could* still have a flag that implicitly adds "docrootdir" to the beginning of known asset path attributes, making it unnecessary to manually add the attribute...but under the covers it would still work as though it had been added explicitly.

-Dan


--
Reply | Threaded
Open this post in threaded view
|

Re: Single CSS for multiple, nested adoc files

mojavelinux
Administrator
In reply to this post by ChrLipp
I also want to clarify that "docrootdir" does not have a direct correlation with any particular file. It's not the same, for instance, as "docdir". The "docrootdir" is a synthetic value that comes into existence when processing many files.

The "docrootdir" attribute is the path distance from the directory where the output file ends up and the output directory supplied to the invocation of Asciidoctor.

For example, if you run Asciidoctor recursively on:

src/main/asciidoc

and the output directory is

target/html

when this file is processed:

src/main/asciidoc/quickstart/quickstart-1.adoc

it ends up in

target/html/quickstart/quickstart-1.html

the docrootdir is ".."

-Dan


On Sat, Sep 14, 2013 at 12:24 AM, Dan Allen <[hidden email]> wrote:



On Thu, Sep 12, 2013 at 1:54 AM, ChrLipp [via Asciidoctor :: Discussion] <[hidden email]> wrote:

Solution E ::

- Copy the CSS manually.
- Link to the stylesheet with stylesdir and linkcss
- Provide an additional flag like useRelativeCssLinking which takes the adoc path and the css path and tries to compute a relative path. If this is possible, use it. If not, stick to the absolute path.

As I started to say in a previous response, the problem with something like useRelativeCssLinking is that this is not just an issue with CSS. The issue is with asset references in the output file.

I think we need to explore the following two solutions, and see which one plays out as most viable:

a. Provide a "docrootdir" attribute that can be used, perhaps in various ways, to keep the asset path consistent with the current directory level.
b. Recognize a relative directory for any attribute that ends with "dir" and adjust the value to reflect the current directory level

Instinct tells me that (b) is going to be very fragile and likely to confuse users that weren't on the design committee :) Although it seems like an extra step, using an attribute makes the intent very clear and gives us *lots* of room for doing smart things.

Now, we *could* still have a flag that implicitly adds "docrootdir" to the beginning of known asset path attributes, making it unnecessary to manually add the attribute...but under the covers it would still work as though it had been added explicitly.

-Dan



--
Reply | Threaded
Open this post in threaded view
|

Re: Single CSS for multiple, nested adoc files

mojavelinux
Administrator
In reply to this post by ChrLipp
We need an issue to track this request. The issue should be named according to the requirement, not a particular solution. Something like:

"references to assets should remain consistent when processing documents in nested directories"

-Dan


On Sat, Sep 14, 2013 at 12:32 AM, Dan Allen <[hidden email]> wrote:
I also want to clarify that "docrootdir" does not have a direct correlation with any particular file. It's not the same, for instance, as "docdir". The "docrootdir" is a synthetic value that comes into existence when processing many files.

The "docrootdir" attribute is the path distance from the directory where the output file ends up and the output directory supplied to the invocation of Asciidoctor.

For example, if you run Asciidoctor recursively on:

src/main/asciidoc

and the output directory is

target/html

when this file is processed:

src/main/asciidoc/quickstart/quickstart-1.adoc

it ends up in

target/html/quickstart/quickstart-1.html

the docrootdir is ".."

-Dan


On Sat, Sep 14, 2013 at 12:24 AM, Dan Allen <[hidden email]> wrote:



On Thu, Sep 12, 2013 at 1:54 AM, ChrLipp [via Asciidoctor :: Discussion] <[hidden email]> wrote:

Solution E ::

- Copy the CSS manually.
- Link to the stylesheet with stylesdir and linkcss
- Provide an additional flag like useRelativeCssLinking which takes the adoc path and the css path and tries to compute a relative path. If this is possible, use it. If not, stick to the absolute path.

As I started to say in a previous response, the problem with something like useRelativeCssLinking is that this is not just an issue with CSS. The issue is with asset references in the output file.

I think we need to explore the following two solutions, and see which one plays out as most viable:

a. Provide a "docrootdir" attribute that can be used, perhaps in various ways, to keep the asset path consistent with the current directory level.
b. Recognize a relative directory for any attribute that ends with "dir" and adjust the value to reflect the current directory level

Instinct tells me that (b) is going to be very fragile and likely to confuse users that weren't on the design committee :) Although it seems like an extra step, using an attribute makes the intent very clear and gives us *lots* of room for doing smart things.

Now, we *could* still have a flag that implicitly adds "docrootdir" to the beginning of known asset path attributes, making it unnecessary to manually add the attribute...but under the covers it would still work as though it had been added explicitly.

-Dan



--



--
Reply | Threaded
Open this post in threaded view
|

Re: Single CSS for multiple, nested adoc files

ChrLipp
The issue is here: https://github.com/asciidoctor/asciidoctor/issues/633
Please apologize my wording, English is not my mothertongue. Feel free to update it.

Thanks for the support,
kind regards

Christian