mailing-list for TeXmacs Users

[address@hidden]

On Tue, Dec 10, 2002 at 03:54:43PM +0100, Nicolas Girard wrote:
> Thank you for these informations, but i'm afraid i don't understand your
> reaction. Could you please tell me where the troll is ?

Sorry for blowing up. Actually the mail was much softer than early
drafts... I should have refrained from saying you were trolling.

I just had the general impression you were roughly saying "I don't
wanna do what ya told me" (remember the Rage Against The Machine
song?) and that you were trying to confuse the issue by citing a mail
from me which was not really relevant to the current discussion.

Apologies... I just should try harder to keep cool.


> You raised an interesting point for which i created a new thread:
> "how to hack TeXmacs styles ?" ; at least it appears very important
> to me. After reading your advice i had the feeling that your
> way of hacking styles was very different than mine and i would
> be glad to use the Right Way ; however:
> -1- the use of default format has always been the most natural to me 
> -2- the use of scheme code isn't obvious to me
> 
> I certainly badly and quickly exposed these two points, but how could
> you imagine i was trolling, while i was just trying to find a way
> to make my styles work ???

Okay. So let us stop arguing and let us concentrate a constructive
discussion.

> So let me go into details:
> 
> -1- Maybe i should explain you how i've been hacking styles up to now,
> and maybe i should stick to the problem from which this discussion
> arised.
> 
> In fact the need to modify headers comes from one of my colleagues ;
> i convinced our administrator to install a copy of TeXmacs for
> everybody and succeeded in having several people discovering
> TeXmacs ; but you'll understand that i can't go and tell our
> admin once a week "come on ! time to upgrade TeXmacs to the
> brand new version !" ; so as a first parenthesis i'd like
> to say that it is natural for users to come to you with outdated
> code, because sometimes they just have to deal with an
> outdated-but-working installation.

First, congratulations for you advocacy work. And you made a point
that in a corporate context, it may be necessary to work with an
outdated release of TeXmacs.

But you can understand that we might not have time to go out of our
way to figure out how to make things work on old versions that we are
no longer working on. Hopefully at some point there will be more
knowledgeable users to answer those requests (and I believe we are
doing our best to reach that point).

Also, we hope that in the future we will be able to provide commercial
user support. And someday there may be a real "stable" TeXmacs branch
(not just a "stable" snapshot). But at the moment we are really
lacking manpower, and all our work goes to the experimental releases.

In the meantime, if you do not have too fascist an administrator, you
may install TeXmacs locally on your account (say, in ~/pub/local) and
prepare a shell script to let other users configure their ~/.profile
to use it. So you do not have to ask your sysadmin for every upgrade
of TeXmacs.


> Okay, so once i understood the guy's need, i browsed all *.ts
> files and looked for everything that looked like "header". It
> quickly appeared that the code responsible for article headers
> was in the file 'packages/header/header-article.ts'
> 
> The next step was to create a file named 'my-article.ts', similar
> to the file named 'article.ts', in which i put all relevant
> code i could find in the file 'header-article.ts'. my-article
> then looked something like:
> 
> <TeXmacs|1.0.0.17>
> 
> <style|<tuple|common-base|header-article|env-us|number-article|section-articl\
> e>>
> 
> <\body>
>   <assign|my-article-style|1.0>
> 
>   <assign|odd-page-text|<func|s|<assign|odd page header|<with|font
>   size|0.84|<format|no first indentation><with|font
>   shape|small-caps|<apply|s>><htab|5mm><quote|<apply|page number>>>>>>
> 
>   <assign|even-page-text|<func|s|<assign|even page header|<with|font
>   size|0.84|<format|no first indentation><quote|<apply|page
>   number>><htab|5mm><with|font shape|small-caps|<apply|s>>>>>>
> 
>   [.......]
> 
> Of course, code formatted like this is unreadable, so i re-arrange it before
> any modifications, like the following chunk:

Right. That sucks.


>   <assign|odd-page-text|<func|s|\
>     <assign|odd page header|<with|font size|0.84|\
>       <format|no first indentation>
>       <with|font shape|small-caps|<apply|s>>
>       <htab|5mm>
>       <quote|<apply|page number>>\
>     >>\
>   >>

Here come the first problems. Unescaped return (subsequent unescaped
spaces) are parsed as a single space. So you were introducing spaces
after <format>, <with> and <htab>. The correct version would have
been:

    <assign|odd-page-text|<func|s|\
     <assign|odd page header|<with|font size|0.84|\
       <format|no first indentation>\
       <with|font shape|small-caps|<apply|s>>\
       <htab|5mm>\
       <quote|<apply|page number>>\
     >>\
   >>


> Then i hack it until it works... most of time i'm successful,
> and sometimes not ; in the late case i ask the mailing-list.
> That's it.
> 
> I hope you'll agree that i could not invent the above macros, i had
> to copy existing code to see how things worked, and it happened to come
> to me as *default format* and not as scheme code. Hardly all my knowledge
> of TeXmacs guts come from existing .tm and .ts files i hacked and played 
> with,
> and this is why i told you that in my situation this code is de facto the 
> most
> natural to me since it is the one i explored.
> 
> So please tell me what you think about my way of hacking styles,
> which i thought to be straightforward. How do you personnally
> hack styles ?

What I would have done is create a style myarticle.ts, whose document
style is "article", so it inherits all the definitions in the standard
article file. Then create a new document which use myarticle.ts.

Then I would use TeXmacs to add definitions on myarticle.ts, and see
how the changes affect my test document.

Now I am used to the horrible layout of the preamble mode, but I
understand it can be a real obstacle to comprehension for less
experienced users. One things which helps a lot to figure how things
are working is using incremental selection (multiple presses to
C-space) to see graphically the scope of the constructs.

If I really cannot understand what a definition does, I select
"Tools->Selection->Export->Scheme" and copy-paste the definition to
emacs in a buffer in Scheme mode, so I can lay it out readably.

But I does all modifications directly in TeXmacs so I do not have to
deal with the esoterics of the TeXmacs document formats.

> -2- As i had very few experience with scheme code, it has always seemed
[...]
> So probably it would be very helpful if you could 'demistify' TeXmacs
> scheme code, and especially tell me about the following points
> i find particularly obscure: 
> - is there a simple reciepe to do the translation between the two formats?
> Given a chunk of default code, how to translate it to scheme code, and
> vice-versa ?

Simple might not be the word, but I can try.

  elements -- generally, simple elements are translated directly. In
    Scheme format, the element name is represented by a symbol, and
    string nodes (except names of expansions which contain no space
    and do not have the same name as a typesetter element) are
    represented as strings.

  (foo (bar "Hello,") " World!) --> <foo|<bar|Hello,> World!>

  escaping -- In TeXmacs format, pipes "|", angle brackets "<" and ">"
   and backslashes must be backslash escaped. In Scheme format, double
   quotes '"' and backslash must be backslash escaped.

  spaces -- in texmacs format, multiple spaces are collapsed to a
    single space. To represent multiple spaces, each space after the
    first space mist be collapsed. In Scheme format, multiple spaces
    are simply multiple spaces in string nodes.

    For example: (foo "   ") --> <foo| \ \ >

  paragraphs -- paragraphs are structure elements in TeXmacs. Any
    multiparagraph part is represented as an embedded 'document' node.
    In TeXmacs format, the pargraphs are represented in a 'pretty' but
    non-obvious way. If an element contains a paragraph as one of its
    subtrees it is broken is several tags. In Scheme format, the
    'document' nodes are represented as is.

  For example:
    (foo (document "hello")) -->
      <\foo>
        hello
      </foo>
    (foo "bar" (document "hello")) -->
      <\foo|bar>
        hello
      </foo>

    There are additional notations for other position of 'document'
    nodes, but these two are what you will see 99% of the time.
    
    When a document contains multiple paragraphs, they are separated
    by a blank line in texmacs format. Empty paragraphs are denoted by
    a line containing "\;" in texmacs format.

  For example;
    (foo (document "Hello," "World!")) -->
      <\foo>
        Hello,

        World!
      </foo>

    (foo (document "Hello," "" "World)) -->
      <\foo>
        Hello,

        \;

        World!
      </foo>

  concats -- elements take a fixed number of parameters, but those
    parameters may directly contain several elements so we need
    intermediate nodes to perform aggregation. When a parameter is
    multiparagraph, the (first) intermediate node is document. When
    the parameter is a sequence of line items, they are aggregate
    using 'concat' nodes.

  For example:

    (foo (concat (em "Hello") ", World!)) --> <foo|<em|Hello>, World!>

    (foo (document (concat (em "Hello") ",") "World!")) -->
    <\foo>
      <em|Hello>,

      World!
    </foo>


I hope at this point you are convinced that the Scheme format is
indeed *simpler* than the TeXmacs format, since it has fewer rules.


> - is it possible to mix default format and scheme code in .ts files?

No. A document is either is Scheme format or in TeXmacs format.


> - is it possible to use only scheme code in .ts files ?

No, as far as I know.


> - if the use of scheme code for styles is the Right Way, then why
>   do .ts files contain no scheme code ?

Scheme format used to be the native format for all document in ancient
versions of TeXmacs. Then Joris designed the TeXmacs format and made
it the default for all documents. TeXmacs style files name must end in
".ts" and files whose name end in ".tm" or ".ts" are assummed to be in
TeXmacs format. Only files whose name end in ".scm" are treated as
Scheme files.


> - how precisely do concats work ? i'm sorry but even after your last
>   explanation i still understand nothing to this ; i also read
>   this paragraph about concats in the documentation which just added to my
>   confusion:
>   " (concat t1 ... tn): Horizontal concatenation of the trees t1, ..., tn.
>     Often, but not always, the main edit tree are concatenations. "
>     ~~~~~~~~~~~~~~~~~~~~~

See the previous explanation.

I do not not know what the "often but not always" refers to. In my
experience, the main edit tree is *always* a 'document' tree which may
contain various elements (strings for text-only paragraphs, expansions
for line containing only a macro expansion like a section name or a
theorem, concats for paragraph which contain mixed text and
structure).


> And please, if you still see trolls in the above conversation,
> consider having a break ! Remember: watching TV, having a bud...

Not troll at all here. Please ask if you want additional information.

And once it is clear in your mind, you may consider contributing a
documentation explaining the whole issue from the ground up.

-- 
David Allouche         | GNU TeXmacs -- Writing is a pleasure
Free software engineer |    http://www.texmacs.org
   http://ddaa.net     |    http://alqua.com/tmresources
   address@hidden  |    address@hidden
TeXmacs is NOT a LaTeX front-end and is unrelated to emacs.