Ordered List (Alphabetical) and HTML Export

Ordered List (Alphabetical) and HTML Export

[Josiah Schwab]

Hi All,

I am using orgmode 8.0.3 with emacs 24.3.  I frequently use
ordered lists with alphabetical bullets.  I have
  (setq org-list-allow-alphabetical t)
in my .emacs.

I just noticed that when I export an alphabetical list using the HTML
exporter, it appears as a numerical list in the rendered HTML.  My
expectation was that the ol tags for this list would look like <ol
type="a">, but instead they are just plain <ol>. (At the end of the
message is a snippet that lets you reproduce this.)

From poking around in ox-html.el (specfically, looking at
org-html-begin-plain-list), I see that there is no code that handles
the list "type".

I spent a few minutes looking at org-list.el, but I'm new enough to
both org-mode and elisp, that I couldn't immediately see how to extend
org-html-begin-plain-list so that it could figure out the kind of list
bullet and properly set the type.

Could anyone help walk me through what one would need to do to get the
desired behavior of HTML export preserving alphabetically bulleted
lists?

Best,
Josiah Schwab

P.S.  Here's an example org snippet.

* Letters
a. foo
b. bar
c. baz
* Numbers
1. foo
2. bar
3. baz

Re: Ordered List (Alphabetical) and HTML Export

[Bastien]

Hi Josiah,

Josiah Schwab <jschwab@gmail.com> writes:

> I am using orgmode 8.0.3 with emacs 24.3.  I frequently use
> ordered lists with alphabetical bullets.  I have
>   (setq org-list-allow-alphabetical t)
> in my .emacs.

You should be able to export them to <ol type="a"> lists now
(from the maint branch, which will be the next stable release.)

-- 
 Bastien

Re: Ordered List (Alphabetical) and HTML Export

[Nicolas Goaziou]

Hello,

Bastien <bzg@gnu.org> writes:

> Josiah Schwab <jschwab@gmail.com> writes:
>
>> I am using orgmode 8.0.3 with emacs 24.3.  I frequently use
>> ordered lists with alphabetical bullets.  I have
>>   (setq org-list-allow-alphabetical t)
>> in my .emacs.
>
> You should be able to export them to <ol type="a"> lists now
> (from the maint branch, which will be the next stable release.)

I don't think this is a good change.

As explained in this thread, alphabetical lists are only a visual clue
(and a bad one, IMO) which have no particular meaning wrt export (Org
only recognizes `ordered', `unordered' and `description' lists). This is
why this "feature" was never implemented in the last exporter.

The OP can probably use CSS to get what he wants without hard coding it
in the back-end.

Moreover, it introduces an incompatibility with `latex' back-end, since
this one won't enforce alphabetical bullets in the same situation.

Therefore, I suggest to revert the patch.


Regards,

-- 
Nicolas Goaziou

Re: Ordered List (Alphabetical) and HTML Export

[Bastien]

[-- Attachment #1: Type: text/plain, Size: 534 bytes --]

Hi Nicolas,

Nicolas Goaziou <n.goaziou@gmail.com> writes:

> Therefore, I suggest to revert the patch.

This simple .tex file allows for alphabetical enumeration.

Given that Org allows alphabetical list, the OP question is
natural and will come back.  There is no clue in Org that
alphabetical lists are just visual clues.

I see no harm in supporting more flexibility where we can.

E.g. the attached .tex file produces alphabetical lists,
it should be simple enough to implement this in ox-latex.el.

Let me know what you think,


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: enumerate_alpha.tex --]
[-- Type: text/x-tex, Size: 150 bytes --]

\documentclass[12pt]{article}
\usepackage{enumerate}

\begin{document}
\begin{enumerate}[a.]
\item Item 1
\item Item 2
\end{enumerate}
\end{document}

[-- Attachment #3: Type: text/plain, Size: 14 bytes --]


-- 
 Bastien

Re: Ordered List (Alphabetical) and HTML Export

[Bastien]

Bastien <bzg@altern.org> writes:

> I see no harm in supporting more flexibility where we can.

I should add that Org is a way for many LaTeX newbies to discover
LaTeX, supporting alphabetical lists in LaTeX (and other backend)
goes into this direction IMO.

-- 
 Bastien

Re: Ordered List (Alphabetical) and HTML Export

[Sebastien Vauban]

Hello,

Bastien wrote:
> Bastien <bzg-whniv8GeeGkdnm+yROfE0A@public.gmane.org> writes:
>
>> I see no harm in supporting more flexibility where we can.
>
> I should add that Org is a way for many LaTeX newbies to discover LaTeX,
> supporting alphabetical lists in LaTeX (and other backend) goes into this
> direction IMO.

Speaking of lists, when I showed Org mode this week-end to some "hard LaTeX
guy", when he saw that we could choose between "-", "+" and "*" for itemized
lists and between "1." and "1)" for enumerated lists (whichever the depth
level), he suggested (for enumerated lists) that:

- 2nd level items should be:

    (a) ...
    (b) ...
    (c) ...
    (d) ...

- 3rd level items should be:

      i. ...
     ii. ...
    iii. ...
     iv. ...

    or:

    i. ...
    ii. ...
    iii. ...
    iv. ...

- 4th level items should be:

    A. ...
    B. ...
    C. ...
    D. ...

It is what is implemented (following typographical rules?) for both French and
English (at least) in LaTeX. See:

--8<---------------cut here---------------start------------->8---
\documentclass[english,french]{article}
\usepackage[T1]{fontenc}
\usepackage[utf8]{inputenc}
\usepackage{babel}
%
\begin{document}
\newcommand{\test}{%
  \begin{enumerate}
  \item
    \begin{enumerate}
    \item
      \begin{enumerate}
      \item
        \begin{enumerate}
        \item
        \item
        \item
        \item
        \end{enumerate}
      \item
      \item
      \item
      \end{enumerate}
    \item
    \item
    \item
    \end{enumerate}
  \item
  \item
  \item
  \end{enumerate}
}
\test{}
\selectlanguage{english}
\test{}
\end{document}
--8<---------------cut here---------------end--------------->8---

Dunno what you think about that, dunno if that's feasible and easy... But
wanted to share with you his point of view...

Best regards,
  Seb

-- 
Sebastien Vauban

Re: Ordered List (Alphabetical) and HTML Export

[Nicolas Goaziou]

Bastien <bzg@altern.org> writes:

> Given that Org allows alphabetical list, the OP question is
> natural and will come back.

Of course it will. And it had been discussed when the feature was
introduced. I don't mind discussing it again, but there's nothing new on
the table. I thought it had a FAQ entry: I was wrong.

> There is no clue in Org that alphabetical lists are just visual clues.

The manual is one clue. Quoting section "2.7 Plain lists"

   Org knows ordered lists, unordered lists, and description lists.
   * _Unordered_ list items start with '-', '+', or '*'(1) as bullets.
   * _Ordered_ list items start with a numeral followed by either a
     period or a right parenthesis(2), such as '1.' or '1)'(3).  If you
     want a list to start with a different value (e.g., 20), start the
     text of the item with '[@20]'(4).  Those constructs can be used in
     any item of the list in order to enforce a particular numbering.
   * _Description_ list items are unordered list items, and contain the
     separator ' :: ' to distinguish the description _term_ from the
     description.

"Alphabetical list" is only a footnote in this paragraph and clearly not
a type on its own. Merely a convenience.

> I see no harm in supporting more flexibility where we can.

Only where it makes sense: this is not Org's job to replace CSS. Org is
about structure, not appearance.

Also, I do see harm. Introducing a "feature" in one major back-end means
updating other major back-ends, for the sake of consistency. LaTeX (as
in "pdflatex") already does a good job to produce item markers. It is
also configurable. Enforcing it is almost certainly a bad idea anyway.

Let's think about it. If user has a non-nil
`org-list-allow-alphabetical' and don't use them, should we make sure
that items are _never_ alphabetical in the output (i.e. always numbers)?
Also, what if users start asking for roman numbers as item markers?
Greek letters? Of course, Org doesn't provide them in the buffer, but
doesn't it sound silly to offer alphabetical lists only when so many
other types are supported by the targeted languages? Shouldn't back-ends
do the extra step in that direction?

We must draw a clear line between what Org should and shouldn't do. IMO,
this patch is on the wrong side of the line.

> Let me know what you think,

I think the same as I did way back when we introduced this. I don't like
alphabetical lists and I don't think we should offer more support for
them. I would be happier if there was less possible bullets in Org
syntax. This probably won't happen, but I see no reason to make the
situation worse.


Regards,

-- 
Nicolas Goaziou

Re: Ordered List (Alphabetical) and HTML Export

[Bastien]

(I've removed the feature from maint (and master) so that we can take
the time to discuss it.)

Nicolas Goaziou <n.goaziou@gmail.com> writes:

> Bastien <bzg@altern.org> writes:
>
>> Given that Org allows alphabetical list, the OP question is
>> natural and will come back.
>
> Of course it will. And it had been discussed when the feature was
> introduced. I don't mind discussing it again, but there's nothing new on
> the table. I thought it had a FAQ entry: I was wrong.
>
>> There is no clue in Org that alphabetical lists are just visual clues.
>
> The manual is one clue. Quoting section "2.7 Plain lists"
>
>    Org knows ordered lists, unordered lists, and description lists.
>    * _Unordered_ list items start with '-', '+', or '*'(1) as bullets.
>    * _Ordered_ list items start with a numeral followed by either a
>      period or a right parenthesis(2), such as '1.' or '1)'(3).  If you
>      want a list to start with a different value (e.g., 20), start the
>      text of the item with '[@20]'(4).  Those constructs can be used in
>      any item of the list in order to enforce a particular numbering.
>    * _Description_ list items are unordered list items, and contain the
>      separator ' :: ' to distinguish the description _term_ from the
>      description.
>
> "Alphabetical list" is only a footnote in this paragraph and clearly not
> a type on its own. Merely a convenience.

There is no clue in here.  The way it is, the manual seems to suggest
that alphabetical lists are supported (including in the export) as
long as you have (setq org-list-allow-alphabetical t).  We need to
make the manual more explicit here.

>> I see no harm in supporting more flexibility where we can.
>
> Only where it makes sense: this is not Org's job to replace CSS. Org is
> about structure, not appearance.

Structure vs. appearance is a useful distinction, but very often it is
overrated as a way to think about what a tool should/should not do.

> Also, I do see harm. Introducing a "feature" in one major back-end means
> updating other major back-ends, for the sake of consistency. LaTeX (as
> in "pdflatex") already does a good job to produce item markers. It is
> also configurable. Enforcing it is almost certainly a bad idea anyway.
>
> Let's think about it. If user has a non-nil
> `org-list-allow-alphabetical' and don't use them, should we make sure
> that items are _never_ alphabetical in the output (i.e. always numbers)?

Clearly no.

> Also, what if users start asking for roman numbers as item markers?

<ol type="I"> works fine.  There are solutions for LaTeX too.

> Greek letters? Of course, Org doesn't provide them in the buffer, but
> doesn't it sound silly to offer alphabetical lists only when so many
> other types are supported by the targeted languages? Shouldn't back-ends
> do the extra step in that direction?

No.  This users can clearly understand: there are (at least human)
limits to what we can implement.  But this is different that saying
him: "Exporting a) b) c) as 1. 2. 3. is a feature, not a bug."

> We must draw a clear line between what Org should and shouldn't do. IMO,
> this patch is on the wrong side of the line.

The patch was too bold, I give you that :)

>> Let me know what you think,
>
> I think the same as I did way back when we introduced this. I don't like
> alphabetical lists and I don't think we should offer more support for
> them. I would be happier if there was less possible bullets in Org
> syntax. This probably won't happen, but I see no reason to make the
> situation worse.

I would perfectly understand that it's too much maintainance ahead.
This sounds perfectly reasonable to me -- and (perhaps paradoxically)
less arbitrary than "this does not fit Org's function, this is only
aesthetic."

Alphabetical lists are aesthetic sugar both in Org and its outputs,
and Org is nice because it tries to keep the input and output both 
structurally and aesthetically similar.

For example, horizontal lines in table are purely aesthetic, both
in Org and its output.  (They may have semantic value within the
document, but just as alphabetical bullets.)  Users expect Org to
do a good job at putting the right horizontal lines in the output
because it matters to them.

Now: I tend to draw the line between what matters to users and what
does not matter, not using the structure vs. aesthetic distinction,
which is very relative.  IOW, I'd ask the users if then want it or
not.

Ok, end of rant, back to code :)

Thanks,

-- 
 Bastien

Re: Ordered List (Alphabetical) and HTML Export

[Nicolas Goaziou]

Bastien <bzg@gnu.org> writes:

> (I've removed the feature from maint (and master) so that we can take
> the time to discuss it.)

Fair enough.

>> Let's think about it. If user has a non-nil
>> `org-list-allow-alphabetical' and don't use them, should we make sure
>> that items are _never_ alphabetical in the output (i.e. always numbers)?
>
> Clearly no.

Interesting. As you know, pdflatex will produce, at some levels, alpha
bullets for ordered lists, unless told otherwise. So,

  a. Item     exported to     1. Item

is wrong (hence your patch), but

  1. Item     exported to     (a) Item

isn't wrong (according to your answer). I just cannot make sense out of
it. Either Org controls totally its output (my head hurts just thinking
about it) or it doesn't. Your patch stands in-between: it's confusing.

>> Also, what if users start asking for roman numbers as item markers?
>
> <ol type="I"> works fine.  There are solutions for LaTeX too.

Of course there are solutions. For ODT, too. But I certainly don't want
to open that can of worms.

>> Greek letters? Of course, Org doesn't provide them in the buffer, but
>> doesn't it sound silly to offer alphabetical lists only when so many
>> other types are supported by the targeted languages? Shouldn't back-ends
>> do the extra step in that direction?
>
> No.  This users can clearly understand: there are (at least human)
> limits to what we can implement.  But this is different that saying
> him: "Exporting a) b) c) as 1. 2. 3. is a feature, not a bug."

That's not what we are telling him. Likewise, we are not promising that
exporting a "- " item will always call for a hyphen in the output: it
may be a bullet instead.

The only promise wrt bullet type and export is: export will preserve
`ordered', `unordered' and `description' status of plain lists. That's
all. Supporting this "simple" thing already requires hundreds lines of
code in some export back-ends.

Currently, in Org syntax, "a) b) c)" is an alias for "ordered list", as
"1) 2) 3)".

> I would perfectly understand that it's too much maintainance ahead.
> This sounds perfectly reasonable to me -- and (perhaps paradoxically)
> less arbitrary than "this does not fit Org's function, this is only
> aesthetic."

OK. Count me in the "too much maintenance ahead", then.

> Alphabetical lists are aesthetic sugar both in Org and its outputs,

I do not agree with "and its outputs" part, since there was nothing in
this direction before your patch.

> and Org is nice because it tries to keep the input and output both
> structurally and aesthetically similar.

Does it? In Beamer back-end, a block is very different, visually
speaking, from a headline.

> Now: I tend to draw the line between what matters to users and what
> does not matter, not using the structure vs. aesthetic distinction,
> which is very relative.  IOW, I'd ask the users if then want it or
> not.

There can be no line between "what matters to users" and "what does
not", because wherever you may put that line, someone will always be
interested in a feature on the other side. Tell me about relative
distinctions ;)

I'll take "structure vs. aesthetics" anytime, because you can always
argue about it. On the other hand, there's not much to say when someone
tells you: "this feature is very important in my daily work, let's
provide it".

> Ok, end of rant, back to code :)

Whatever the conclusion of this thread is, I hope it will make for a FAQ
entry so we do not start it over every now and then.


Regards,

-- 
Nicolas Goaziou

Re: Ordered List (Alphabetical) and HTML Export

[Jambunathan K]

The buck stops with the maintainer of the files.  It is only polite and
good etiquette that any change that is not-trivial or not-routine be
discussed beforehand.

Sneaking in changes - just because it can be done in 5 minutes - is what
a jerk would do.

Re: Ordered List (Alphabetical) and HTML Export

[Bastien]

Hi Nicolas,

Nicolas Goaziou <n.goaziou@gmail.com> writes:

> Whatever the conclusion of this thread is, I hope it will make for a FAQ
> entry so we do not start it over every now and then.

Here is it: http://orgmode.org/worg/org-faq.html#sec-11-5

-- 
 Bastien

Re: Ordered List (Alphabetical) and HTML Export

[Carsten Dominik]

On 1.7.2013, at 13:49, Nicolas Goaziou <n.goaziou@gmail.com> wrote:

> Bastien <bzg@altern.org> writes:
> 
>> Given that Org allows alphabetical list, the OP question is
>> natural and will come back.
> 
> Of course it will. And it had been discussed when the feature was
> introduced. I don't mind discussing it again, but there's nothing new on
> the table. I thought it had a FAQ entry: I was wrong.
> 
>> There is no clue in Org that alphabetical lists are just visual clues.
> 
> The manual is one clue. Quoting section "2.7 Plain lists"
> 
>   Org knows ordered lists, unordered lists, and description lists.
>   * _Unordered_ list items start with '-', '+', or '*'(1) as bullets.
>   * _Ordered_ list items start with a numeral followed by either a
>     period or a right parenthesis(2), such as '1.' or '1)'(3).  If you
>     want a list to start with a different value (e.g., 20), start the
>     text of the item with '[@20]'(4).  Those constructs can be used in
>     any item of the list in order to enforce a particular numbering.
>   * _Description_ list items are unordered list items, and contain the
>     separator ' :: ' to distinguish the description _term_ from the
>     description.
> 
> "Alphabetical list" is only a footnote in this paragraph and clearly not
> a type on its own. Merely a convenience.
> 
>> I see no harm in supporting more flexibility where we can.
> 
> Only where it makes sense: this is not Org's job to replace CSS. Org is
> about structure, not appearance.


Hi,

as I have expressed earlier in a different thread, I think Nicolas
is right here.  The backend should decide how lists (ordered and unordered)
are formatted, because this is the right way construct document structure.

LaTeX and HTML are really the guide there.  Lists are written with
enumerate and itemize, and the style sets the bullets for different levels.

When I write documents, I often choose only different types of bullets to
make it easier for me to remember what level I am on.  I think in almost
all cases the structure created by a good document formatter will provide
the cleanest and most readable output.

So I would like to keep the current convention.  If we must, we can have
something like the [@N] to enforce a particular bullet style.

- Carsten

> 
> Also, I do see harm. Introducing a "feature" in one major back-end means
> updating other major back-ends, for the sake of consistency. LaTeX (as
> in "pdflatex") already does a good job to produce item markers. It is
> also configurable. Enforcing it is almost certainly a bad idea anyway.
> 
> Let's think about it. If user has a non-nil
> `org-list-allow-alphabetical' and don't use them, should we make sure
> that items are _never_ alphabetical in the output (i.e. always numbers)?
> Also, what if users start asking for roman numbers as item markers?
> Greek letters? Of course, Org doesn't provide them in the buffer, but
> doesn't it sound silly to offer alphabetical lists only when so many
> other types are supported by the targeted languages? Shouldn't back-ends
> do the extra step in that direction?
> 
> We must draw a clear line between what Org should and shouldn't do. IMO,
> this patch is on the wrong side of the line.
> 
>> Let me know what you think,
> 
> I think the same as I did way back when we introduced this. I don't like
> alphabetical lists and I don't think we should offer more support for
> them. I would be happier if there was less possible bullets in Org
> syntax. This probably won't happen, but I see no reason to make the
> situation worse.
> 
> 
> Regards,
> 
> -- 
> Nicolas Goaziou
> 

Re: Ordered List (Alphabetical) and HTML Export

[Bastien]

Nicolas Goaziou <n.goaziou@gmail.com> writes:

>>> Let's think about it. If user has a non-nil
>>> `org-list-allow-alphabetical' and don't use them, should we make sure
>>> that items are _never_ alphabetical in the output (i.e. always numbers)?
>>
>> Clearly no.
>
> Interesting. As you know, pdflatex will produce, at some levels, alpha
> bullets for ordered lists, unless told otherwise. So,
>
>   a. Item     exported to     1. Item
>
> is wrong (hence your patch), but
>
>   1. Item     exported to     (a) Item
>
> isn't wrong (according to your answer). I just cannot make sense out of
> it. Either Org controls totally its output (my head hurts just thinking
> about it) or it doesn't. Your patch stands in-between: it's confusing.

Maybe I misunderstand your question.

If a user has (setq org-list-allow-alphabetical t) but don't use
alphabetical lists, I don't see where is the problem.

> The only promise wrt bullet type and export is: export will preserve
> `ordered', `unordered' and `description' status of plain lists. That's
> all. Supporting this "simple" thing already requires hundreds lines of
> code in some export back-ends.

I know.  But speaking of structure vs. appearance: ODT has no notion
of descriptive lists, this is just a visual emulation of it.  So the
choice of limiting the syntax to `ordered', `unordered', `description'
is fine to me, but has some arbitrary ground too.

> Currently, in Org syntax, "a) b) c)" is an alias for "ordered list", as
> "1) 2) 3)".
>
>> I would perfectly understand that it's too much maintainance ahead.
>> This sounds perfectly reasonable to me -- and (perhaps paradoxically)
>> less arbitrary than "this does not fit Org's function, this is only
>> aesthetic."
>
> OK. Count me in the "too much maintenance ahead", then.

Fair enough.

>> Alphabetical lists are aesthetic sugar both in Org and its outputs,
>
> I do not agree with "and its outputs" part, since there was nothing in
> this direction before your patch.

I was speaking of alphabetical lists in general: they are aesthetic
sugar in HTML as well (i.e. there is no <aol> tag for "alphabetical
ordered list".)

>> and Org is nice because it tries to keep the input and output both
>> structurally and aesthetically similar.
>
> Does it? In Beamer back-end, a block is very different, visually
> speaking, from a headline.

It does where it can.

-- 
 Bastien