Le 16/01/2013 12:34, Lex Trotman a écrit :
Hi Jens, Stuart,
I just went for a walk around the block and I think I now understand
it so let me present the current situation in excruciating detail, and
Stuart can correct as appropriate.
Starting with data-uri set, this is easy since the image path is only
used for an input because the image is embedded. The target is
relative to the directory of the input file (or output if input is not
from a file) with imagesdir interposed if defined. Imagedir and
target can be relative or absolute, it doesn't matter since its just
read for creation of the embedded data. Being relative to the input
file (the one containing the image:: even if its included in another
document) supports subdocuments being processed alone or as part of
the aggregate document.
Fine so far.
This is how usually paths in subdocuments are interpreted, see LaTeX for ex.
With data-uri not set asciidoc must generate links to the image files.
As Stuart pointed out there are situations where links to absolute
paths will not work, so its reasonable for asciidoc to only generate
relative links. These links must be relative to the *output* file so
the browser/server can find them. As Stuart pointed out it is
potentially difficult to generate these from an input file path, so in
fact the user must specify the link contents in imagesdir/ (if
defined) and target.
I must admit I did not understand that difficulty. Maybe my view is too
simplistic.
I follow your argumentation. "AsciiDoc should generate relative links."
- all right for
me. You say relative to the *output* file. for ex. whole_doc.html (see
2. solution).
For me the solution is to concatenate systematically:
path from masterdocument to subdocument + path to image
(as it
appears in
chapter1/contents.asciidoc). Here:
chapter1/ + images/image1.png
This gives the path that is rendered in whole_doc.html.
************* begin proposal
I imagine some guys like to have all images in one folder:
whole_doc.asciidoc
whole_doc.html
chapter1/contents.asciidoc
images/image1.png
images/image2.png
According to the above solution, If he wants to include image1.png in
chapter1/contents.asciidoc he must write:
image::./../images/image1.png[]
This is not very handy. I suggest the following convention:
If a path starts with a leading "/" then this "/" refers to the folder
where
the master document resides. So the above could be shortened to:
image::/images/image1.png[]
With this convention everybody should be happy. Those who like to refer
to the master documents folder, and those who need to refer to the
subdocuments folder.
************** end proposal
This isn't really clearly pointed out in the
docs I don't think.
The data-uri and non-data-uri situations are in fact specifying
different things and thats why they are different. In most cases
nobody notices since in most cases indir and outdir are the same or
only data-uri or links are used, its only in the case of documents
processed both with and without data-uri and in more than one
directory that the problem occurs. Since this is the unusual use-case
We can see it this way: If this strange behaviour was not noticed so
far, we
can correct it without breaking many existing documents.
AsciiDoc targets the processing of large documents. Large documents are
usually
split in independent parts, compiled, then proof-read and assembled very
late.
In many cases large documents are written by different authors. In my
point of view subdocuments being processed first alone and then as part
of the aggregate document is a very common work flow for large documents.
I think asciidoc should be left as is and alternate solutions
considered.
I think the way paths are treated mustn't depend on a directive like
:data-uri:
This is very confusing and should be defined in a consistent way.
So one solution is that indir must be the same as outdir in all cases,
ie all asciidoc and output files must be in the one dir:
whole_doc.asciidoc
whole_doc.html
chapter_1.asciidoc
chapter1.html
chapter_2.asciidoc
chapter_2.html
etc
chapter1_images/image_1.png
chapter1_images/image_2.png
chapter2_images/image_3.png
Note that the images can still be separated in subdirectories but that
asciidoc files must be in the same location.
If having everything in the top level is too messy,
As you say. Especially for large documents this is not acceptable.
My simple use case: I write exercises for students. Each exercise
resides with
all its files in one directory. Later I assemble them with a master
document.
For me your 2. following suggestion is much more useful.
then try the directory tree:
whole_doc.asciidoc
whole_doc.html
chapter1/contents.asciidoc
chapter1/contents.html
chapter1/images/image1.png
chapter1/images/image2.png
etc
For this to work, subdocuments must set imagesdir to adjust for the
case of a non-datauri whole document. Now the subdocuments must know
if they are being processed on their own or in the whole document, so
in whole_doc.asciidoc define an attribute, say :whole_doc:
Subdocuments reference images as image::images/image1.png[] and at the
top each of them has:
ifdef::whole_doc[]
ifndef::data-uri[]
:imagesdir: chapter1
endif::data-uri[]
endif::whole_doc[]
If whole_doc.asciidoc has any image macros the it will have to
undefine imagesdir after each include or each subdocument should
undefine it at its end.
Thank you for this workaround! Looks fine for me. But is still a
workaround not
a solution.
What do you think of my proposal?
Cheers
Jens
--
You received this message because you are subscribed to the Google Groups
"asciidoc" group.
To post to this group, send email to [email protected].
To unsubscribe from this group, send email to
[email protected].
For more options, visit this group at
http://groups.google.com/group/asciidoc?hl=en.
