Nabble - AsciiDoc - Discussion

test

2008-05-22T11:14:13Z

test

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

ANN: blogpost 0.9.0 released

2008-05-22T01:52:33Z

There has been a code base rewrite and lots of changes since the first
release
(http://www.nabble.com/ANN%3A-blogpost---Wordpress-weblog-client-for-AsciiDoc-to17270014.html):

- Media files (images, videos, audio, document) referenced in your
AsciiDoc documents are automatically uploaded and linked to the
uploaded blog.
- Only new or modified media files are uploaded (changes detected
using cached MD5 checksums).
- Metadata caching means post options are remembered and don't need to
be repeated every time you update your posts.
- WordPress Pages can be posted and updated (blogpost includes a
patched wordpresslib.py containing Page methods).

My blog on media processing has a couple of embedded images and
explains blogpost media processing:
http://srackham.wordpress.com/2008/05/22/blogpost-media-processing/

Here's a link to a example article from the AsciiDoc (which also
contains images) distribution that I've posted using blogpost to
WordPress.com:
http://srackham.wordpress.com/asciidoc-example-article/

See also the blogpost(1) man page:
http://srackham.wordpress.com/blogpost1/

blogpost has only just dried, please post bug reports and suggestions.

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

Re: fop v0.20 vs v0.95

2008-05-20T20:54:05Z

Mikhail Yakshin wrote:

> Hello, Stuart,
>
> First, I'd like to thank you for your excellent AsciiDoc suite: I'm
> using it already for two of my project and I'm looking for more :)
>
> I was generating HTMLs using AsciiDoc for a while, and recently I've
> came up with a task of PDF generation. Looks like the best way to do
> so it using docbook->fo->pdf chain, but, alas, I've stumbled upon a
> long-lasting problem with .fo documents made by asciidoc toolchain
> (a2x) are not suitable for newer versions of Apache FOP v0.95, but
> compile okay using ancient versions (v0.20.*).
>
> I've seen you mentioning this problem on various forums/mailing lists:
> you wrote that you've got mystical unhandled Java exception and
> there's no way around it. In fact, after spending several hours of
> reading DocBook specifications and DocBook XSL, I've understood that
> it's pretty simple: DocBook XSLs have 2 parameters named
> "fop.extensions" and "fop1.extensions". You don't call DocBook XSLs
> directly, but propagate some default parameters using special "fo.xsl"
> stylesheet, distributed with AsciiDoc. The problem with fop v0.95
> compatibility can be easily solved by replacing "fop.extensions" with
> "fop1.extensions" in that file:
>
> -<xsl:param name="fop.extensions" select="1" />
> +<xsl:param name="fop1.extensions" select="1" />
>
> After that, I've successfully made it work with modern Apache FOP :)
>
> Hope it helps and new version of AsciiDoc would support newer FOP out
> of the box ;)
>

Thank you Mikhail for doing the hard stuff. I've verified it works on
fop-0.95 and have applied your patch:
http://hg.sharesource.org/asciidoc/rev/e1bc93fef523

I've also cc'd this to the asciidoc-discuss mailing list as I'm sure
others will be interested in this.

See also: http://xmlgraphics.apache.org/fop/0.95/upgrading.html

I also had to remove a line defining 'bgcolor' from ./docbook/common.xsl
with it in got the following FOP exception:

SEVERE: Exception
javax.xml.transform.TransformerException:
org.apache.fop.fo.ValidationException:
file:/home/srackham/projects/asciidoc/trunk/doc/asciidoc.fo:471:514:
Error(471/514): fo:block, Invalid property name 'bgcolor'.

This problem was alluded to in a previous post
http://www.mail-archive.com/asciidoc-discuss@.../msg00118.html

Some differences I've noticed between 0.20 and 0.95:

- FOP 0.20.5 scales images if they overflow page width, FOP 0.95beta
does not (./doc/music-filter.pdf).

I must say I'm leaning towards dblatex(1) to generate PDF's:

- dblatex is easy to install (on Linux)
- requires no configuration
- is blindingly fast
- one step conversion, docbook XML to PDF (no FO generation, no need for
XSL Stylesheets and patches, XSLT processing or Java).
- Internal document hyperlinks are implemented (this is really handy).
- The output documents are more compact with about 20% less pages.

The only drawback is that the output is quite plain -- anyone out there
with any dblatex styling experience?

I really need to clean up the FOP stuff in the user guide (FOP install
stuff doesn't really belong) and mention dblatex(1).

Cheers, Stuart
--
Stuart Rackham

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

Re: [PATCH] a2x: allow custom options to fop

2008-05-16T20:16:07Z

Hi Miklos

Patch uploaded to repo: http://hg.sharesource.org/asciidoc/rev/6668cc811844

Thanks for the patch, your patience and for also attending to the man
page changes.

Cheers, Stuart

Miklos Vajna wrote:

> On Mon, May 05, 2008 at 02:34:15AM +0200, Miklos Vajna <vmiklos@...> wrote:
>> http://frugalware.org/~vmiklos/patches/a2x-fop-opts.diff
>>
>> i needed this patch because using accents with the default fonts is
>> problematic in pdf documents, but there was no easy way to pass a custom
>> configuration file. i think it'll be useful for others as well ;)
>
> Stuart, could you please comment this patch? :)
>
> i don't think it would break anything, but i would be happy to get an
> "ack" from you ;)
>
> thanks
>
>
> ------------------------------------------------------------------------
>
> _______________________________________________
> asciidoc-discuss mailing list
> asciidoc-discuss@...
> http://lists.metaperl.com/cgi-bin/mailman/listinfo/asciidoc-discuss

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

Re: [PATCH] a2x: allow custom options to fop

2008-05-16T03:25:18Z

On Mon, May 05, 2008 at 02:34:15AM +0200, Miklos Vajna <vmiklos@...> wrote:
> http://frugalware.org/~vmiklos/patches/a2x-fop-opts.diff
>
> i needed this patch because using accents with the default fonts is
> problematic in pdf documents, but there was no easy way to pass a custom
> configuration file. i think it'll be useful for others as well ;)

Stuart, could you please comment this patch? :)

i don't think it would break anything, but i would be happy to get an
"ack" from you ;)

thanks

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

attachment0 (204 bytes) Download Attachment

ANN: blogpost - Wordpress weblog client for AsciiDoc

2008-05-16T01:33:27Z

I've just released blogpost, a Wordpress command-line weblog client
for AsciiDoc written in Python. It creates and updates weblog entries
directly from AsciiDoc source documents. You can also delete and list
Wordpress weblog entries from the command-line.

Here are some documents I've uploaded to wordpress.com using blogpost:

blogpost Rationale and Overview:
http://srackham.wordpress.com/2008/05/15/blogging-with-asciidoc/

The AsciiDoc User Guide:
http://srackham.wordpress.com/asciidoc-user-guide/

blogpost man page:
http://srackham.wordpress.com/blogpost1/

Project repo and download here:
http://hg.sharesource.org/blogpost/

This is a first release, there will be bugs, please post bug reports
and suggestions.

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

Re: ANN: AsciiDoc 8.2.6

2008-05-12T15:27:23Z

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

Stuart Rackham <srackham@...> writes:

> You're running under Windows so as I had only tested on Linux (Xubuntu
> 7.10) I tried the AsciiDoc distribution article.txt under Windows
> (Windows XP SP2, Python 2.5.2 (I'm not using Cygwin)).
>
> Which rendered the embedded images fine fine (see
> http://www.methods.co.nz/misc/article.html), though I did get non-zero
> exit codes (seems be Python related, doesn't affect the output but I
> haven't got to the bottom of it):

Ah, I see. Your script encodes the image and embeds it. I thought that
it merely embedded it, and so I encoded the image separately. Not
surprisingly, asciidoc didn't seem to know what to do with a
base64-encoded image as input to the process.

Thanks; it worked easily for me today. Now if you'd only get MS to
retrofit this into IE 6 and 7 or get all my clients to switch to FF, I'd
be set. :-)

Thanks again,

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

iD8DBQFIKMRO3J3HaQTDvd8RAoSiAJ9GIVB8H3J2clIn9I50lqyJ0HH+2wCeKeyU
oMYMqmovGZeLjIREgTIFIb4=
=6nHG
-----END PGP SIGNATURE-----
_______________________________________________
asciidoc-discuss mailing list
asciidoc-discuss@...
http://lists.metaperl.com/cgi-bin/mailman/listinfo/asciidoc-discuss

Re: ANN: AsciiDoc 8.2.6

2008-05-11T20:55:45Z

Hi Bill

Bill Harris wrote:

> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
>
> Stuart Rackham <srackham@...> writes:
>
>> The only noteworthy functional addition is embedded image support using
>> the data: URI Scheme (http://en.wikipedia.org/wiki/Data:_URI_scheme) for
>> XHTML documents (it's a nifty demonstration of the use of the {sys}
>> system attribute).
>
> That sounded cool (although I think most of my clients use IE7), so I
> tried it out. While 8.2.6 looks good so far, I can't make this feature
> work. I'd appreciate a clean and full example.
>
> To make life easy (or so I thought -- I'll try cygwin's base64.exe
> later, when I can make this work), I went to
> http://www.sveinbjorn.org/cgi-bin/dataurlmaker-cgi.pl and converted a
> small picture I had on my computer. It gave me a string of the form
>
> <img src="data:image/jpeg;base64,/9j/4AAQ ... bunch of stuff elided ... WrCk460UVYH//Z" width="172" height="243">
>
> I prepended image:: and pasted the resultant into my previously working
> document.
>
> I ran asciidoc.py --unsafe -a data-uri -a toc file.txt.
>
> The resulting HTML file shows image::<"data:image/jpeg... in the output
> instead of a picture. I tested my browser (FF 2.0.0.14) at
> http://www.mozilla.org/quality/networking/testing/datatests.html, and it
> seems to work.
>
> I also tried it without the toc attribute, and I tried something like
> the format in asciidoc.html:
>
> ,----
> | .Main circuit board
> | [caption="Figure 2:"]
> | image::images/layout.png
> `----
>
> except that I used the <> enclosed stuff after image::, too.
>
> Any tips?

You're running under Windows so as I had only tested on Linux (Xubuntu
7.10) I tried the AsciiDoc distribution article.txt under Windows
(Windows XP SP2, Python 2.5.2 (I'm not using Cygwin)).

Which rendered the embedded images fine fine (see
http://www.methods.co.nz/misc/article.html), though I did get non-zero
exit codes (seems be Python related, doesn't affect the output but I
haven't got to the bottom of it):

C:\bin\asciidoc>asciidoc -a data-uri --unsafe doc/article.txt
WARNING: article.txt: line 37: {sys:python -uc "import base64,sys;
base64.encode(sys.stdin,sys.stdout)" < "images/smallnew.png"}: non-zero
exit status
WARNING: article.txt: line 40: {sys:python -uc "import base64,sys;
base64.encode(sys.stdin,sys.stdout)" < "images/tiger.png"}: non-zero
exit status

You can run the same encoding command that asciidoc runs from the DOS
prompt e.g. (one line)

C:\bin\asciidoc>python -uc "import base64,sys;
base64.encode(sys.stdin,sys.stdout)" < "images/tiger.png"

This spews out the base64 encoding that the {sys} attribute embeds in
the XHTML output document (why the exit code is non-zero eludes me, but
as I said before this doesn't affect the output).

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

Re: ANN: AsciiDoc 8.2.6

2008-05-08T14:34:24Z

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

Stuart Rackham <srackham@...> writes:

> The only noteworthy functional addition is embedded image support using
> the data: URI Scheme (http://en.wikipedia.org/wiki/Data:_URI_scheme) for
> XHTML documents (it's a nifty demonstration of the use of the {sys}
> system attribute).

That sounded cool (although I think most of my clients use IE7), so I
tried it out. While 8.2.6 looks good so far, I can't make this feature
work. I'd appreciate a clean and full example.

To make life easy (or so I thought -- I'll try cygwin's base64.exe
later, when I can make this work), I went to
http://www.sveinbjorn.org/cgi-bin/dataurlmaker-cgi.pl and converted a
small picture I had on my computer. It gave me a string of the form

<img src="data:image/jpeg;base64,/9j/4AAQ ... bunch of stuff elided ... WrCk460UVYH//Z" width="172" height="243">

I prepended image:: and pasted the resultant into my previously working
document.

I ran asciidoc.py --unsafe -a data-uri -a toc file.txt.

The resulting HTML file shows image::<"data:image/jpeg... in the output
instead of a picture. I tested my browser (FF 2.0.0.14) at
http://www.mozilla.org/quality/networking/testing/datatests.html, and it
seems to work.

I also tried it without the toc attribute, and I tried something like
the format in asciidoc.html:

,----
| .Main circuit board
| [caption="Figure 2:"]
| image::images/layout.png
`----

except that I used the <> enclosed stuff after image::, too.

Any tips?

Thanks,

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

iD8DBQFII3Hg3J3HaQTDvd8RAvI2AJ91xXHpQf+fX/LtQIp/J9+n8dd/ugCdEf/0
MALQ03MvxLLzffiZV8jNm8Q=
=xjrL
-----END PGP SIGNATURE-----
_______________________________________________
asciidoc-discuss mailing list
asciidoc-discuss@...
http://lists.metaperl.com/cgi-bin/mailman/listinfo/asciidoc-discuss

Re: Unanswered questions etc.

2008-05-06T02:39:03Z

On Tue, 6 May 2008, Stuart Rackham wrote:

> When I'm busy like this I tend to go for the low hanging fruit when it
> comes to responses, leaving the big (usually more important) stuff till
> later.

Exactly the same emergency mode I tend to fall into too often. :)

--
-- dag wieers, dag@..., http://dag.wieers.com/ --
[Any errors in spelling, tact or fact are transmission errors]
_______________________________________________
asciidoc-discuss mailing list
asciidoc-discuss@...
http://lists.metaperl.com/cgi-bin/mailman/listinfo/asciidoc-discuss

Unanswered questions etc.

2008-05-05T16:58:09Z

Please don't think I'm deliberately ignoring questions/patches etc on
the list, I do read everything, it's just that at the moment I'm really
busy -- I wish there were more hours in the day :-)

When I'm busy like this I tend to go for the low hanging fruit when it
comes to responses, leaving the big (usually more important) stuff till
later.

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

[PATCH] a2x: allow custom options to fop

2008-05-04T17:34:15Z

hi,

http://frugalware.org/~vmiklos/patches/a2x-fop-opts.diff

i needed this patch because using accents with the default fonts is
problematic in pdf documents, but there was no easy way to pass a custom
configuration file. i think it'll be useful for others as well ;)

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

attachment0 (204 bytes) Download Attachment

Using multiline variables in configuration file attributes

2008-05-04T07:59:40Z

Hello,

I am looking for a way to use multiline values for attributes in AsciiDoc
configuration files but can't seem to work it out.

Is there a way to do this?

Thanks,

--
Noah Slater - Bytesexual <http://bytesexual.org/>
_______________________________________________
asciidoc-discuss mailing list
asciidoc-discuss@...
http://lists.metaperl.com/cgi-bin/mailman/listinfo/asciidoc-discuss

Using attributes inside other attributes

2008-05-04T07:59:24Z

Hello,

I am having some problems getting attributes inside other attributes to work.

I have the following sample asciidoc.conf:

[attributes]

pubdate = "2008"
author = "Noah Slater"
publisher = "Bytesexual"
copyrightholder = "{publisher={author}}"
copyrightyears = "{pubdate}"

There are two problems I am having with this:

1. the copyrightholder attribute only works if the publisher attribute is set,
if this is undefined the author attribute is not substituted.

2. the copyrightyears attribute remains undefined

The documentation seems to indicate that I can use simple attributes like this.

What am I doing wrong?

I am using AsciiDoc version 8.2.5.

Thanks,

--
Noah Slater - Bytesexual <http://bytesexual.org/>
_______________________________________________
asciidoc-discuss mailing list
asciidoc-discuss@...
http://lists.metaperl.com/cgi-bin/mailman/listinfo/asciidoc-discuss

Re: ANN: AsciiDoc 8.2.6

2008-04-29T14:29:33Z

On Wed, Apr 30, 2008 at 09:17:39AM +1200, Stuart Rackham <srackham@...> wrote:
> I've done limited testing on Windows and Python 2.3 (most testing and
> development on Xubuntu 7.10 + Python 2.5.1), so yell out if you
> experience regression problems.

hm, it seems the tex backend is somewhat broken. here is what i do:

wget -O test.txt http://frugalware.org/~boobaa/stuff/doc-u.txt

$ asciidoc --unsafe --backend=latex -a toc test.txt
WARNING: [music-block] missing template section
WARNING: [music-block] missing template section

but test.tex created properly

this is 8.2.5. after upgrading to 8.2.6:

$ asciidoc --unsafe --backend=latex -a toc test.txt
FAILED: malformed section entry: \\=\textbackslash{}

and no output created. feel free to correct me if this is just a pebkac
:)

thanks.

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

attachment0 (204 bytes) Download Attachment

ANN: AsciiDoc 8.2.6

2008-04-29T14:17:39Z

Hi All

There have been a lot of small (hopefully useful) changes and bug fixes
since 8.2.5 so I thought it was time to formally release them:

http://www.methods.co.nz/asciidoc/CHANGELOG.html

The only noteworthy functional addition is embedded image support using
the data: URI Scheme (http://en.wikipedia.org/wiki/Data:_URI_scheme) for
XHTML documents (it's a nifty demonstration of the use of the {sys}
system attribute).

I've done limited testing on Windows and Python 2.3 (most testing and
development on Xubuntu 7.10 + Python 2.5.1), so yell out if you
experience regression problems.

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

Re: Semantic markup?

2008-04-29T09:51:55Z

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

Re: Semantic markup?

2008-04-29T09:41:24Z

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

Re: Semantic markup?

2008-04-29T07:36:53Z

-----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: +1 425 337-5541
-----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

Re: Semantic markup?

2008-04-28T14:34:55Z

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

Re: Semantic markup?

2008-04-28T12:43:34Z

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

attachment0 (196 bytes) Download Attachment

Re: Semantic markup?

2008-04-28T12:28:32Z

-----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: +1 425 337-5541
-----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

Semantic markup? (was: Re: ToC #hash position patch)

2008-04-27T19:42:38Z

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

Re: patch: correct #hash position after updating ToC

2008-04-27T17:58:10Z

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

Re: patch: correct #hash position after updating ToC

2008-04-26T13:35:50Z

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

Re: patch: correct #hash position after updating ToC

2008-04-26T11:27:18Z

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

attachment0 (204 bytes) Download Attachment

Re: patch: correct #hash position after updating ToC

2008-04-26T10:56:20Z

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

Re: patch: correct #hash position after updating ToC

2008-04-26T06:52:25Z

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

attachment0 (196 bytes) Download Attachment

Re: patch: correct #hash position after updating ToC

2008-04-26T05:19:30Z

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

attachment0 (204 bytes) Download Attachment

Re: patch: correct #hash position after updating ToC

2008-04-26T05:16:12Z

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

attachment0 (204 bytes) Download Attachment

Re: centre aligned text, fonts and colours

2008-04-26T03:24:58Z

Great Alex, thanks a lot.

Rory.

Alex Efros wrote:

> Hi!
>
> On Fri, Apr 25, 2008 at 02:30:51PM +0100, Rory Walsh wrote:
>> To summarise I guess I'm asking if I can create/set my own custom
>> layout/format to an asciidoc text. Any suggestions will be greatly
>> appreciated.
>
> If your output format is html, then most, if not all such things can be
> easily changed using your custom CSS. In all other cases you can
> change existing or write own custom asciidoc config file in /etc/asciidoc/
> and have nearly full control over output format.
>

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

bug? missing empty line after list

2008-04-26T01:01:48Z

Producing a manpage with asciidoc 8.2.5, I observe the following:

- every list is preceeded by an empty line
- but it is not followed by an empty line
This offends logic and readability.
_______________________________________________
asciidoc-discuss mailing list
asciidoc-discuss@...
http://lists.metaperl.com/cgi-bin/mailman/listinfo/asciidoc-discuss

Re: patch: correct #hash position after updating ToC

2008-04-25T21:05:22Z

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

Re: patch: correct #hash position after updating ToC

2008-04-25T20:07:58Z

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

patch: correct #hash position after updating ToC

2008-04-25T20:02:21Z

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