On 17 January 2013 09:25, gmail <[email protected]> wrote: > 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).
Yes, because the link in the output document must be relative to that document, thats an HTML requirement. Asciidoc doesn't actually care where the image file is, since it doesn't read it if its using links. The key thing to understand is that with data-uri you are specifying an input file location, with links you are specifying a link in the output file. Its not the same thing. > > 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. Asciidoc doesn't know about master docs, subdocs, and their directory structure. Asciidoc does not and should not define such things, there are too many use-cases that result in different structures. The user has to do it for Asciidoc, and thats what my version 2 below does. The technique can be adapted for most directory structures. > > > ************* 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[] Correct for subdocuments and whole documents with data-uri, but wrong for whole documents without data-uri. > > 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: You can use imagesdir to hold the common part of the image location, so shortening it to: :imagesdir: ../images image::image1.png[] This is better than a unique convention that conflicts with the universal usage of paths, ie that those starting with / are absolute. > > 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. You still have to change them to be relative to the input file or the output file depending on data-uri. > > ************** 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. > Sadly this definition is caused by the fact that you are defining two different things, as I said above, with data-uri you are specifying an input file location for inclusion, without data-uri you are specifying a link to go in the output file and to be relative to the output file as required by HTML. Generating the relative path can be tricky, especially if it goes up and of course will not work at all for recursive asciidocs which don't have an indir to specify the image path relative to. (Side note: so recursive asciidocs must specify paths relative to the output for both data-uri and non-data-uri which again needs to handle whole-doc changes of output directory). > >> 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. Well, the more I think about it, the more I don't think there is an automatic solution that handles all situations. So in the end explicit user specified handling may have to be the solution. Cheers Lex > > 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. > -- 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.
