patch: correct #hash position after updating ToC

[Alex Efros-4]

Hi!

Problem: after clicking on url with hash like /doc/index.html#something
page loaded positioned on #something, but after updating ToC position
changed (usually ToC push page several lines down).

This behaviour exists in Opera 9/Linux, FF 2/Linux and Safari/Mac.
In IE 6/7 this problem doesn't exists, but looks like proposed patch
doesn't broke anything IE so it should be safe to use it to fix other
browsers.

--- toc.js.orig 2008-04-26 05:40:53.000000000 +0300
+++ toc.js      2008-04-26 05:42:09.000000000 +0300
@@ -66,4 +66,6 @@
   }
   if (entries.length == 0)
     document.getElementById("header").removeChild(toc);
+  if (document.location.hash.length > 0)
+    document.location = document.location;
 }

--
                        WBR, Alex.
_______________________________________________
asciidoc-discuss mailing list
asciidoc-discuss@...
http://lists.metaperl.com/cgi-bin/mailman/listinfo/asciidoc-discuss

[Alex Efros-4]

Hi!

> +    document.location = document.location;

BTW, there side effect in adding additional item in browser history.
So user will need to click 'Back' twice to get to previous pages.
I wonder is it possible to fix this issue without introducing this side
effect (which is just another issue itself, to be honest)?

--
                        WBR, Alex.
_______________________________________________
asciidoc-discuss mailing list
asciidoc-discuss@...
http://lists.metaperl.com/cgi-bin/mailman/listinfo/asciidoc-discuss

[Alex Efros-4]

Hi!

BTW, most ease and correct way to solve (actually - avoid) all issues with
ToC - don't use JavaScript to generate it on the fly. Is there any reasons
why not generate static ToC when generating html itself?

--
                        WBR, Alex.
_______________________________________________
asciidoc-discuss mailing list
asciidoc-discuss@...
http://lists.metaperl.com/cgi-bin/mailman/listinfo/asciidoc-discuss

[Miklos Vajna]

On Sat, Apr 26, 2008 at 07:05:22AM +0300, Alex Efros <powerman@...> wrote:
> BTW, most ease and correct way to solve (actually - avoid) all issues with
> ToC - don't use JavaScript to generate it on the fly. Is there any reasons
> why not generate static ToC when generating html itself?

i guess that's because asciidoc reads the input as a stream, without
buffering. obviously it can't print the toc when it does not see the end
of the input.

i think a solution would be to buffer the ouput in case the output is a
file and not stdin.


_______________________________________________
asciidoc-discuss mailing list
asciidoc-discuss@...
http://lists.metaperl.com/cgi-bin/mailman/listinfo/asciidoc-discuss

[Miklos Vajna]

On Sat, Apr 26, 2008 at 02:16:12PM +0200, Miklos Vajna <vmiklos@...> wrote:
> i think a solution would be to buffer the ouput in case the output is a
> file and not stdin.

in case the input*

sorry for the typo.


_______________________________________________
asciidoc-discuss mailing list
asciidoc-discuss@...
http://lists.metaperl.com/cgi-bin/mailman/listinfo/asciidoc-discuss

[Alex Efros-4]

Hi!

On Sat, Apr 26, 2008 at 02:16:12PM +0200, Miklos Vajna wrote:
> i think a solution would be to buffer the ouput in case the output is a
> file and not stdin.

Not necessarily. There no reason to put all possible functionality into
single tool. I think it's better to develop additional script which will
process document and output ToC. Actually, I suppose such a "tool" can be
just separate config file for asciidoc:

- user run asciidoc asking to convert file.txt using xhtml11.conf
  * asciidoc run another asciidoc asking to convert file.txt using ToC.conf
    and wait until it finish and return prepared static ToC
  * asciidoc process file.txt as usually plus output result of previous
    asciidoc run in place of ToC

I will not be surprised if this can be done using current functionality -
I remember something about possibility to run external command from .conf
file. Source highlight work this way AFAIK.

--
                        WBR, Alex.


_______________________________________________
asciidoc-discuss mailing list
asciidoc-discuss@...
http://lists.metaperl.com/cgi-bin/mailman/listinfo/asciidoc-discuss

[Alex Efros-4]

Hi!

On Sat, Apr 26, 2008 at 06:07:58AM +0300, Alex Efros wrote:
> I wonder is it possible to fix this issue without introducing this side
> effect (which is just another issue itself, to be honest)?

Of course it's possible. :) Fixed version below.

--- toc.js.orig 2008-04-26 05:40:53.000000000 +0300
+++ toc.js      2008-04-26 05:42:09.000000000 +0300
@@ -66,4 +66,6 @@
   }
   if (entries.length == 0)
     document.getElementById("header").removeChild(toc);
+  if (document.location.hash.length > 0)
+    document.location.replace(document.location.hash);
 }

--
                        WBR, Alex.
_______________________________________________
asciidoc-discuss mailing list
asciidoc-discuss@...
http://lists.metaperl.com/cgi-bin/mailman/listinfo/asciidoc-discuss

[Miklos Vajna]

On Sat, Apr 26, 2008 at 04:52:25PM +0300, Alex Efros <powerman@...> wrote:
> - user run asciidoc asking to convert file.txt using xhtml11.conf
>   * asciidoc run another asciidoc asking to convert file.txt using ToC.conf
>     and wait until it finish and return prepared static ToC
>   * asciidoc process file.txt as usually plus output result of previous
>     asciidoc run in place of ToC
>
> I will not be surprised if this can be done using current functionality -
> I remember something about possibility to run external command from .conf
> file. Source highlight work this way AFAIK.

they are called filters. i'm not sure if you can pass the whole file.txt
to a filter as well (the source highlight works just for given code
blocks).


_______________________________________________
asciidoc-discuss mailing list
asciidoc-discuss@...
http://lists.metaperl.com/cgi-bin/mailman/listinfo/asciidoc-discuss

[Stuart Rackham]

Alex Efros wrote:

> Hi!
>
> On Sat, Apr 26, 2008 at 02:16:12PM +0200, Miklos Vajna wrote:
>> i think a solution would be to buffer the ouput in case the output is a
>> file and not stdin.
>
> Not necessarily. There no reason to put all possible functionality into
> single tool. I think it's better to develop additional script which will
> process document and output ToC. Actually, I suppose such a "tool" can be
> just separate config file for asciidoc:
>
> - user run asciidoc asking to convert file.txt using xhtml11.conf
>   * asciidoc run another asciidoc asking to convert file.txt using ToC.conf
>     and wait until it finish and return prepared static ToC
>   * asciidoc process file.txt as usually plus output result of previous
>     asciidoc run in place of ToC
>
> I will not be surprised if this can be done using current functionality -
> I remember something about possibility to run external command from .conf
> file. Source highlight work this way AFAIK.

ToC generation does break the single pass implementation of asciidoc.
With regards static ToC, you can do this using DocBook XSL Stylesheets
toolchain (the JS XHTML ToC is a quick and dirty way to get a ToC if you
haven't configured the toolchain). The DocBook route also adds the
option of generating chunked XHTML documents. Here's the chunked User
Guide example: http://www.methods.co.nz/asciidoc/chunked/index.html

Cheers, Stuart
_______________________________________________
asciidoc-discuss mailing list
asciidoc-discuss@...
http://lists.metaperl.com/cgi-bin/mailman/listinfo/asciidoc-discuss

[Stuart Rackham]

Alex Efros wrote:

> Hi!
>
> On Sat, Apr 26, 2008 at 06:07:58AM +0300, Alex Efros wrote:
>> I wonder is it possible to fix this issue without introducing this side
>> effect (which is just another issue itself, to be honest)?
>
> Of course it's possible. :) Fixed version below.
>
> --- toc.js.orig 2008-04-26 05:40:53.000000000 +0300
> +++ toc.js      2008-04-26 05:42:09.000000000 +0300
> @@ -66,4 +66,6 @@
>    }
>    if (entries.length == 0)
>      document.getElementById("header").removeChild(toc);
> +  if (document.location.hash.length > 0)
> +    document.location.replace(document.location.hash);
>  }
>

With this patch I still get positioning problems in IE7 (7.0.6001.18000).

Cheers, Stuart
_______________________________________________
asciidoc-discuss mailing list
asciidoc-discuss@...
http://lists.metaperl.com/cgi-bin/mailman/listinfo/asciidoc-discuss

[Alex Efros-4]

Hi!

On Mon, Apr 28, 2008 at 12:58:10PM +1200, Stuart Rackham wrote:
> With this patch I still get positioning problems in IE7 (7.0.6001.18000).

Actually, that's not important. I think right solution will be to generate
static ToC. Even with current one-pass asciidoc realization it's still
possible to plug ToC generation script before asciidoc:
    cat file.txt | add_ToC | asciidoc -

So I think this patch shouldn't be included in asciidoc. Most people live
without it for a long time, few who need it - will find it in maillist...
while we can focus on right solution. ;-)


BTW, there one more thing which keep bothering me: idea about making
generated html more semantic. Of course asciidoc can't add semantic if
there no semantic markup in source file, so this should be applied to
source file first. As example. I wrote documentation about software tools,
projects, articles about software, etc. This sort of documentation
contains inside text (i.e. inlined, not as separate blocks) things like
filenames, short examples of commands, specific terms, references to man
pages, etc... - in addition to usual simple bold/italic/underline text
markup. I'd like to be able to markup filenames as "filenames" in source
file, i.e. in different way I markup usual bold/italic/monospaced in text.
And generated html should use different css class names for filenames and
usual bold/italic/monospaced text - this allow to distinguish them using
usual css. What you think about this idea? Is there any reasons why this
can't/shouldn't be done which I don't know?

As for me, at least two different markup for italic ('' and __) and
monospace (`` and ++) should generate 4 different css class names instead
of 2. This isn't enough but adding 2 more to 3 existing will nearly double
amount of available markups! Things like ^super^ and ~sub~ are rarely used
in software documentation, so they also can be reused for different things.

Here is how it can be realized to really add semantic information instead
of just changing css and making it incompatible with other asciidoc texts
(which will use ^super^ for making text looks super :) and not to markup
references to man pages):
- at document header user can redefine attributes (or include file with
  such attribute declarations because they are likely will be same for
  many similar documents)
- these attributes set user-defined css class names to possible markup
  (not to all, of course, only to markup user wish to redefine):
    :markup-underscore:    underline
    :markup-quote:    pathname
    :markup-backticks:    command
    :markup-tilde:    ref2man
- file with such redefined attributes will generate html with semantic
  class names and specially crafted css, which support these classes (in
  addition to usual default classes) will show this html better than
  default css... but it will be still possible to use default css for such
  file or use that extended css to process usual asciidoc files

--
                        WBR, Alex.
_______________________________________________
asciidoc-discuss mailing list
asciidoc-discuss@...
http://lists.metaperl.com/cgi-bin/mailman/listinfo/asciidoc-discuss

[Bill Harris]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Just curious: what's your intended distinction among asciidoc, LaTeX,
and DocBook?  I see them as three distinct tools, useful for three
distinct categories of work:

  asciidoc: easy generation of simple documents
  LaTeX:    high-quality typesetting
  DocBook:  semantic markup, document single-sourcing and reuse

If you begin to add functionality to asciidoc to cover semantic markup
as you've described, when does it become more efficient just to write
DocBook source?  If I write in DocBook, at least I have tools such as
nxml-mode to make life easier, and I've got schemas and DTDs that have
been honed by many a user and many a standards meeting.

Bill
- --
Bill Harris                      http://facilitatedsystems.com/weblog/
Facilitated Systems                              Everett, WA 98208 USA
http://facilitatedsystems.com/                  phone: [phone]
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.7 (MingW32)
Comment: For more information, see http://www.gnupg.org

iD8DBQFIFiVk3J3HaQTDvd8RAqrEAJ9zvVcxE8OJ/ypfsJ+EGC6skQAKiQCfeS+i
qaclG+bqpKq7IJ+AY/F7jvU=
=IE0b
-----END PGP SIGNATURE-----
_______________________________________________
asciidoc-discuss mailing list
asciidoc-discuss@...
http://lists.metaperl.com/cgi-bin/mailman/listinfo/asciidoc-discuss

[Alex Efros-4]

Hi!

On Mon, Apr 28, 2008 at 12:28:32PM -0700, Bill Harris wrote:
>   DocBook:  semantic markup, document single-sourcing and reuse

In short, I try to avoid overcomplicated things. DocBook is
overcomplicated - at least for me and my tasks.

Writing documentation is hard task for most software engineers, and if
they can't write documentation using their usual text editor without
spending time for additional things like markup (and especially - XML-like
markup!) - they will try to avoid writing documentation at all.

Using text editor specially designed to edit DocBook isn't an option,
because nearly all Vim and Emacs users unable to use other text editors -
they lack too many useful features or require too many time for learning
one more (needless!) text editor.

So... if we can add some semantic to asciidoc without making it and it
usage more complex... why not? Maybe this feature allow few more people to
migrate from DocBook to AsciiDoc. :)

--
                        WBR, Alex.


_______________________________________________
asciidoc-discuss mailing list
asciidoc-discuss@...
http://lists.metaperl.com/cgi-bin/mailman/listinfo/asciidoc-discuss

[Stuart Rackham]

Alex Efros wrote:

> Hi!
>
> On Mon, Apr 28, 2008 at 12:58:10PM +1200, Stuart Rackham wrote:
>> With this patch I still get positioning problems in IE7 (7.0.6001.18000).
>
> Actually, that's not important. I think right solution will be to generate
> static ToC. Even with current one-pass asciidoc realization it's still
> possible to plug ToC generation script before asciidoc:
>     cat file.txt | add_ToC | asciidoc -
>
> So I think this patch shouldn't be included in asciidoc. Most people live
> without it for a long time, few who need it - will find it in maillist...
> while we can focus on right solution. ;-)

I agree that the patch is not really necessary, in my opinion the
solution is to use the DocBook XSL Stylesheets toolchain (as per my
previous posting:
http://www.nabble.com/forum/ViewPost.jtp?post=16917259&framed=y

>
>
> BTW, there one more thing which keep bothering me: idea about making
> generated html more semantic. Of course asciidoc can't add semantic if
> there no semantic markup in source file, so this should be applied to
> source file first. As example. I wrote documentation about software tools,
> projects, articles about software, etc. This sort of documentation
> contains inside text (i.e. inlined, not as separate blocks) things like
> filenames, short examples of commands, specific terms, references to man
> pages, etc... - in addition to usual simple bold/italic/underline text
> markup. I'd like to be able to markup filenames as "filenames" in source
> file, i.e. in different way I markup usual bold/italic/monospaced in text.
> And generated html should use different css class names for filenames and
> usual bold/italic/monospaced text - this allow to distinguish them using
> usual css. What you think about this idea? Is there any reasons why this
> can't/shouldn't be done which I don't know?

There's absolutely no reason why any or all of this can't be done (by
writing a custom configuration file containing changes and additions to
the existing markup).

Whether there are reasons it should be done is a separate question.
Rather than answering this question directly it's probably easier if I
describe the rationale behind the current AsciiDoc markup and it's
relationship to semantic markups.

The AsciiDoc markup is a fairly simple and general presentational
markup, it was designed that way -- the markup elements relate mostly to
document structure and textual highlighting, the markup conventions are
designed to keep the visual appearance as close as possible to a normal
document. The out-of-the-box markup not meant to be a semantic markup
(at least not in the DocBook sense), perhaps it should be called
'Structural Markup'.

The primary goals of AsciiDoc's markup, in order of importance, are:

- Human readable an writable (any documents should be read comfortably
by readers with no prior knowledge of AsciiDoc).

- Simple (for humans to learn and memorize).

- Generalized (not overly biased toward specific problem domains).

All three design criteria are interdependent.

While the ability to style a document independent of the markup is
good (I would say essential), semantic markup (outside of document
structural elements), while intellectually appealing, has very limited
practical utility for presentational documents (i.e. documents whose
primary function is to be read by humans). After all, do you really need
additional annotations to remind yourself that the text is a file name
(or a menu command or a source code listing)? If you do the document is
probably poorly written. All that's needed are a few unobtrusive text
highlighting and document structuring conventions which the the author
is free to style and use as taste and the target audience dictates.

As soon as you go down the semantic path you are immediately up against
the AsciiDoc design criteria:

- Semantic markup elements are invariably biased towards a particular
problem domain (software documentation in the case of DocBook).

- There is a proliferation of new (often seldom used) elements to the
detriment of readability and simplicity.

There's is an argument that you need semantic markup to enforce
consistency in output documents -- I would counter that a writer who is
incapable of maintaining simple formatting conventions would almost
certainly be incapable of consistently applying semantic markup.

Again, having said all that, there's no reason you can't configure the
AsciiDoc markup to be as semantic as you like. It may even be a
good idea if you specialize in one one or two problem domains.


[...]


Cheers, Stuart
_______________________________________________
asciidoc-discuss mailing list
asciidoc-discuss@...
http://lists.metaperl.com/cgi-bin/mailman/listinfo/asciidoc-discuss

[Bill Harris]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Stuart Rackham <srackham@...> writes:

> The primary goals of AsciiDoc's markup, in order of importance, are:
>
> - Human readable an writable (any documents should be read comfortably
> by readers with no prior knowledge of AsciiDoc).
>
> - Simple (for humans to learn and memorize).
>
> - Generalized (not overly biased toward specific problem domains).

Hi Stuart, Alex,

That last is the reason I asked my question.  I see asciidoc as a
general tool.  I use it for certain client reports, for example, as well
as for taking notes and other tasks.  I started using it for generating
presentations, but I found I liked beamer itself better than the initial
asciidoc beamer extensions (although I applaud that work and can see its
utility).

I was concerned that too much of a focus on semantic markup might make
this more of a software documentation tool and less of a general tool.
I have used DocBook to write documents that don't pertain to software,
but I admit that it fits the software documentation role quite well.
(With nxml-mode, this Emacs user feels no need for a specialized
editor.)

I am very happy with the three objectives you stated here.  If you stay
focused on those, I'm not worried about any extensions you might add.
If you add objectives (e.g., document software well), I'm concerned that
you may risk compromising your second and third goals.  I see that using
this to document software could be very handy; while I haven't been
following the discussion closely, I hope Stuart's suggestions offer you
help, Alex.

Thanks for the cool tool.

Bill
- --
Bill Harris                      http://facilitatedsystems.com/weblog/
Facilitated Systems                              Everett, WA 98208 USA
http://facilitatedsystems.com/                  phone: [phone]
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.7 (MingW32)
Comment: For more information, see http://www.gnupg.org

iD8DBQFIFzKI3J3HaQTDvd8RAqMLAJ9qOQurUybq314/46RaHYmb764p7ACeJroy
fR3na65rkOaX99vaC5AsC7w=
=zo/G
-----END PGP SIGNATURE-----
_______________________________________________
asciidoc-discuss mailing list
asciidoc-discuss@...
http://lists.metaperl.com/cgi-bin/mailman/listinfo/asciidoc-discuss

[Alex Efros-4]

Hi!

On Tue, Apr 29, 2008 at 09:34:55AM +1200, Stuart Rackham wrote:
> Rather than answering this question directly it's probably easier if I
> describe the rationale behind the current AsciiDoc markup and it's
> relationship to semantic markups.

Thanks, this is really important and interesting.

> [...] semantic markup (outside of document structural elements), while
> intellectually appealing, has very limited practical utility for
> presentational documents (i.e. documents whose primary function is to be
> read by humans).

Agreed.

> After all, do you really need additional annotations to remind yourself
> that the text is a file name (or a menu command or a source code listing)?

:) No, I don't need this.

But I'm trying to define some general guidelines "which markup use for
what" in all our software documentation - just to keep it consistent.

It's ok to have several documents written without such consistency (for
example if they was written by different authors), but when several people
write many documents for different parts of same software project - we
have to use common style, just like in code! Without this it will be hard
to read such documentation, where on first page file name was italic, on
second bold, and on third is doesn't have special markup at all. Keeping
in mind case with one author edit documentation written initially by
another... no, thanks, we really need to use consistent markup! :)

> There's is an argument that you need semantic markup to enforce
> consistency in output documents -- I would counter that a writer who is
> incapable of maintaining simple formatting conventions would almost
> certainly be incapable of consistently applying semantic markup.

Agreed. But you doesn't count case with many authors, mentioned above.

> Again, having said all that, there's no reason you can't configure the
> AsciiDoc markup to be as semantic as you like. It may even be a
> good idea if you specialize in one one or two problem domains.

Ok, let me reformulate my question without word "semantic" (which is nice,
cool, wow, etc. but result in misunderstanding here and now).

I need to provide a table like:
    `...` used for command examples
    '...' used for filenames and menu items
    _..._ used to emphasize some text
    *...* alternative way to emphasize some text
    etc. etc.
for all people who will write documentation for our projects.
This is ease, don't require any changes in asciidoc configuration, etc.

Next, I found same visual presentation used for too many items, because:
a)  '...' and _..._ generate same css class name
b)  `...` and +...+ generate same css class name
c)  ^...^ and ~...~ has useless for us visual presentation and
                    so should be avoided
d)  ``...''         is questionable because it usually enough to use usual
                    "..." and reuse ``...'' for something more important
That mean while AsciiDoc support 8 different markup types inside text,
we can use only 5 of them, and these 5 have only 3 different visual
presentations. 8->3 is significant limitation, and I trying to solve this
issue in some way.

Of course I can create custom asciidoc configuration and custom css to
solve this, but this will make our documents incompatible with any other
asciidoc configuration/css. If this is unavoidable we can probably live
with it, but I want to keep our documents as compatible as possible.

Keeping in mind compatibility, we have to avoid using ^...^ and ~...~
because their default visual presentation are too conspicuous and can't be
used for anything else. Other 6 markup types (having 4 different visual
presentations in default configuration) are less conspicuous and can be
used for our custom visual presentations. Actually, we'll need to have
italic, bold and monospace anyway, so actual incompatibility with default
configuration/styles will be limited to:
a) _..._    will probably mean underline instead of italic (only '...'
            will be used for italic, as in default configuration)
b) +...+    will probably mean something special for us with non-standard
            css style (i.e. not monospace) (the `...` will be used for
            monospace, as in default configuration)
c) ``...''  will probably mean something special too, also with non-standard
            css style (usual "..." will be used to markup quoted text
            without any css style for it)
This way we'll have twice more visual presentations (6 instead of 3) with
our custom configuration/css and our documents will still looks good with
default asciidoc configuration!

Next idea was to avoid possible visual disorientation when our documents
will be used with default configuration. For example, if we'll use ``...''
for something custom, in default configuration such things will be
enclosed in quotation marks and may looks strange because quotation marks
will be inappropriate in that place. The idea was to define non-standard css
class names for markup WITHIN document, using attributes for example.
In this case even if standard asciidoc config/css will be used to convert
these documents, the markup with changed meaning will looks like normal
text (because standard css doesn't provide styles for non-standard class
names generated by standard configuration because of these attributes)
and so will not looks inappropriate, at least.

That last idea is only thing which require asciidoc modifications and
maybe it's just overkill and not really useful feature at all.

--
                        WBR, Alex.
_______________________________________________
asciidoc-discuss mailing list
asciidoc-discuss@...
http://lists.metaperl.com/cgi-bin/mailman/listinfo/asciidoc-discuss

[Alex Efros-4]

Hi!

On Tue, Apr 29, 2008 at 07:41:24PM +0300, Alex Efros wrote:

> Next idea was to avoid possible visual disorientation when our documents
> will be used with default configuration. For example, if we'll use ``...''
> for something custom, in default configuration such things will be
> enclosed in quotation marks and may looks strange because quotation marks
> will be inappropriate in that place. The idea was to define non-standard css
> class names for markup WITHIN document, using attributes for example.
> In this case even if standard asciidoc config/css will be used to convert
> these documents, the markup with changed meaning will looks like normal
> text (because standard css doesn't provide styles for non-standard class
> names generated by standard configuration because of these attributes)
> and so will not looks inappropriate, at least.
>
> That last idea is only thing which require asciidoc modifications and
> maybe it's just overkill and not really useful feature at all.

It may worth to note this feature not only allow to avoid possible
disorientation because of non-standard usage of ``...'', but also it allow
us to use ^...^ and ~...~ (which will turn into normal text with standard
configuration instead of super/sub text which will add much more
disorientation than quotation marks), i.e. all 8 markup types supported by
asciidoc!

--
                        WBR, Alex.
_______________________________________________
asciidoc-discuss mailing list
asciidoc-discuss@...
http://lists.metaperl.com/cgi-bin/mailman/listinfo/asciidoc-discuss