many questions

[Patrice Dumas]

Hello,

texi2html is now mostly compatible with makeinfo, but I still
have some questions about the desired bahaviour:

* in the doc it is said that when doing html and split and it is not
  possible to do the directory with the out file basename, .html is
  appended to the directory name. I think this is a very strange and
  bad behaviour. It certainly allows to avoid appending .??? to the
  @setfilename argument and still not have conflicts, but I think that
  forcing users to change @setfilename is better.

  Would it be ok to remove this feature?

* for makeinfo, the following are not the same, looks like -I is not taken
  into account with a leading ./:
@include ./d2t_singular/surf_lib_noEx.tex
@include d2t_singular/surf_lib_noEx.tex

Is it on purpose?

* texinfo expands @-commands normally in @documentdescription, but keeps --,
  texi2html uses simple_format which removes most @commands but uses
  entities

Which one is right (I'd say texi2html)?

* makeinfo in title, for @code{something} leads to `something'. In
texi2html all the style commands are removed without extra formatting.

Is it right?

* makeinfo don't warn for empty deffn, but texi2dvi cannot process them

should there be a warning?

* makeinfo doesn't warn for empty sectionning/heading commands, like
** unnumberedsubsec without name (l. 284)

Should there be a warning or not?

* the code of xml.c in makeinfo shows specific treatement of & in
  definition arguments. Could you please explain what it is meant to
  be?

* makeinfo warn when there is no @settitle nor @top. Guess it is for <title>
  texi2html uses @settitle @title @shorttitlepage @titlefont for <title>.

What should be the best?

* does --document-language cmd line apply to first or all files, when there
  are more than one file on command line?

* In info, when there are multiple index entries with the same name,
  should <1>... be appended? Or only when they are not at the same location?

* only texi2html warns an empty @item in (v|f)table:
** Empty index entry for @vtable (l. 26)
Is it right?

* What are the encodings known by info/makeinfo?
  unrecognized encoding name `ascii'.

* for a construct like

@table @emph
before first table
@item tab
@end table

  leading to something along

    before first table
_tab_

  Should there be an empty line added after the title?

* should @OE{} be associated with '00D8' or '0152'?

* should include files be searched in current directory, input manual
  directory or both?

* When there is a 0x7F as a comment character, should the eol also be
  removed (I think so)?

* When should the following error message be produced:
@strong{Note...} produces a spurious cross-reference in Info; reword to avoid that.

When there is @strong{note or @strong{Note ? In some other cases?

--
Pat

[Karl Berry]

Hi Patrice,

      forcing users to change @setfilename is better.

Well, I don't think it's better to "force" users to change, but maybe
there's a better solution.

      Would it be ok to remove this feature?

Let's come back to this next week.

    * texinfo expands @-commands normally in @documentdescription, but
      keeps --, texi2html uses simple_format which removes most
      @commands but uses entities

    Which one is right (I'd say texi2html)?

Yes, texi2html behavior sounds ok.  I don't think I've ever seen a real
document that used @documentdescription, anyway.

    * makeinfo in title, for @code{something} leads to `something'. In
    texi2html all the style commands are removed without extra formatting.
    Is it right?

Given that @code leads to `...' in general, I don't see why it should
simply be ignored in titles.  It isn't ignored in titles in any other
kind of output, so why in Info?

    * makeinfo don't warn for empty deffn, but texi2dvi cannot process them

Well, that's a bug in texi2dvi.  I'll take a look when I have a chance
(or Oleg ... ?).

    should there be a warning?

I presume texi2html can handle them ok, in which case I'd say, no
warning (regardless of what we can do in texinfo.tex).  Not everyone
cares about processing through TeX.

    * makeinfo doesn't warn for empty sectionning/heading commands, like
    ** unnumberedsubsec without name (l. 284)

    Should there be a warning or not?

Warning is good.

    * the code of xml.c in makeinfo shows specific treatement of & in
      definition arguments. Could you please explain what it is meant to
      be?

    * makeinfo warn when there is no @settitle nor @top. Guess it is for <title>
      texi2html uses @settitle @title @shorttitlepage @titlefont for <title>.

    What should be the best?

texi2html's behavior is better.

    * does --document-language cmd line apply to first or all files, when there
      are more than one file on command line?

It's never come up.  I guesss it should be all files.

    * In info, when there are multiple index entries with the same name,
      should <1>... be appended? Or only when they are not at the same
      location?

I'm not sure.  We should experiment with the Info readers.  Let's come
back to this later.

    * only texi2html warns an empty @item in (v|f)table:
    ** Empty index entry for @vtable (l. 26)
    Is it right?

Warning is good.

    * What are the encodings known by info/makeinfo?
      unrecognized encoding name `ascii'.

See the documentencoding node in texinfo.txi.  US-ASCII, because that's
what the HTML likes, as I recall.  I did not put in the zillion possible
synonyms and map them all to the HTML name that works.

      Should there be an empty line added after the title?

This idea of text outside any @item in the table has never been part of
Texinfo, so whatever behavior is best for you is fine.

    * should @OE{} be associated with '00D8' or '0152'?

@OE{} is the OE ligature (analogous to @AE{} -> AE), so 0152.

Isn't 00D8 "O with stroke" completely different?  I don't understand ...

    * should include files be searched in current directory, input manual
      directory or both?

Both.  Images too.

    * When there is a 0x7F as a comment character, should the eol also be
      removed (I think so)?

Yes.

    * When should the following error message be produced:
    @strong{Note...} produces a spurious cross-reference in Info; reword
    to avoid that.  When there is @strong{note or @strong{Note ?

Right.

    In some other cases?

1) when the arg to @strong is exactly "note", case-insensitive.
2) when the arg begins with the five chars "note ", case-insensitive.

Thanks,
Karl

[Patrice Dumas]

On Mon, Aug 03, 2009 at 04:06:21PM -0500, Karl Berry wrote:
>
>     * makeinfo in title, for @code{something} leads to `something'. In
>     texi2html all the style commands are removed without extra formatting.
>     Is it right?
>
> Given that @code leads to `...' in general, I don't see why it should
> simply be ignored in titles.  It isn't ignored in titles in any other
> kind of output, so why in Info?

In fact I was very unclear. Here I am speaking about title in html
(and more generally strings in attributes in html, but also in @copying
comment). makeinfo formats this kind of text in html like text in
--plaintext or info, while texi2html has a simpler formatting. Which one
is better?

In any case, there is no such thing as a title in Info?

>     * makeinfo don't warn for empty deffn, but texi2dvi cannot process them
>
> Well, that's a bug in texi2dvi.  I'll take a look when I have a chance
> (or Oleg ... ?).
>
>     should there be a warning?
>
> I presume texi2html can handle them ok, in which case I'd say, no
> warning (regardless of what we can do in texinfo.tex).  Not everyone
> cares about processing through TeX.

I didn't meant a warning for TeX. But I think a warning would make sense,
in my opinion an empty @def* is almost surely a mistake, no?

>     * the code of xml.c in makeinfo shows specific treatement of & in
>       definition arguments. Could you please explain what it is meant to
>       be?

No answer, here?

>     * makeinfo warn when there is no @settitle nor @top. Guess it is for <title>
>       texi2html uses @settitle @title @shorttitlepage @titlefont for <title>.
>
>     What should be the best?
>
> texi2html's behavior is better.

Should @top be used if there is none of
@settitle @title @shorttitlepage @titlefont (I don't know)?
and if there is no title should there be a warning if producing html
(I believe so)?

>     * What are the encodings known by info/makeinfo?
>       unrecognized encoding name `ascii'.
>
> See the documentencoding node in texinfo.txi.  US-ASCII, because that's
> what the HTML likes, as I recall.  I did not put in the zillion possible
> synonyms and map them all to the HTML name that works.

Recent Perl do that (and I have a hash for most common older ones as well
as those from makeinfo). But what does the info reader support? Does it
support more than the encodings you listed?

>     * should @OE{} be associated with '00D8' or '0152'?
>
> @OE{} is the OE ligature (analogous to @AE{} -> AE), so 0152.
>
> Isn't 00D8 "O with stroke" completely different?  I don't understand ...

Ok, I am confusing things, let's forget about that, the issue is with
transliteration.

In makeinfo, @O{} is { "Oslash", 0xD8, 0x00D8, "OE" }, which means that it
is transliterated to OE. Is it on purpose that it is not O?

--
Pat

[Patrice Dumas]

On Mon, Aug 03, 2009 at 04:06:21PM -0500, Karl Berry wrote:
>
>     * should include files be searched in current directory, input manual
>       directory or both?
>
> Both.  Images too.

And should files also be searched for in destination directory? I think that
it doesn't matter for input files, but would be better for images.

--
Pat

[Karl Berry]

    And should files also be searched for in destination directory? I think that
    it doesn't matter for input files, but would be better for images.

What scenario do you have in mind with images?

My inclination is to say that searching the destination directory for
any kind of input file, image or otherwise, would just have great
potential for confusion, since the output dir is often some temporary
location; if it happened to include an image by the wrong name ... I
can't think of any other program that does this.  Better for users to
use -I explicitly, I think?

[Patrice Dumas]

On Tue, Aug 04, 2009 at 10:53:26AM -0500, Karl Berry wrote:
>     And should files also be searched for in destination directory? I think that
>     it doesn't matter for input files, but would be better for images.
>
> What scenario do you have in mind with images?

I remember than we agreed that @images paths were relative to the
result file. So, to have paths right, @image should be searched for in
this directory.

> My inclination is to say that searching the destination directory for
> any kind of input file, image or otherwise, would just have great

For input files, indeed it has potential for confusion, but for
images, it seems to me to be rather logical. The issue with
images is that they aren't only something that is inputed in a
manual, they are also part of the final outputed manual (at least
in html).

> potential for confusion, since the output dir is often some temporary
> location; if it happened to include an image by the wrong name ... I
> can't think of any other program that does this.  Better for users to
> use -I explicitly, I think?

I agree, avoiding magic as much as possible is better, indeed.

--
Pat

[Karl Berry]

    I remember than we agreed that @images paths were relative to the
    result file.

Good point.

    So, to have paths right, @image should be searched for in
    this directory.

On the other hand, the arrangement of the source directory could/should
also be the same as the output, if there is any directory structure
involved.

Let's think about this some more and decide next week.

[Oleg Katsitadze]

On Mon, Aug 03, 2009 at 04:06:21PM -0500, Karl Berry wrote:
>     * makeinfo don't warn for empty deffn, but texi2dvi cannot process them
>
> Well, that's a bug in texi2dvi.  I'll take a look when I have a chance
> (or Oleg ... ?).

I've tried this:

    @deffn Command name arg
    @end deffn

and texi2dvi compiled it just fine.

Oleg

[Patrice Dumas]

On Sat, Aug 08, 2009 at 11:44:21PM +0300, Oleg Katsitadze wrote:

> On Mon, Aug 03, 2009 at 04:06:21PM -0500, Karl Berry wrote:
> >     * makeinfo don't warn for empty deffn, but texi2dvi cannot process them
> >
> > Well, that's a bug in texi2dvi.  I'll take a look when I have a chance
> > (or Oleg ... ?).
>
> I've tried this:
>
>     @deffn Command name arg
>     @end deffn

It is

@deffn
@end deffn

Or maybe
@deffn Command
@end deffn

--
Pat

[Oleg Katsitadze]

On Sun, Aug 09, 2009 at 05:14:47PM +0200, Patrice Dumas wrote:

> On Sat, Aug 08, 2009 at 11:44:21PM +0300, Oleg Katsitadze wrote:
> > On Mon, Aug 03, 2009 at 04:06:21PM -0500, Karl Berry wrote:
> > >     * makeinfo don't warn for empty deffn, but texi2dvi cannot process them
> > >
> > > Well, that's a bug in texi2dvi.  I'll take a look when I have a chance
> > > (or Oleg ... ?).
> >
> > I've tried this:
> >
> >     @deffn Command name arg
> >     @end deffn
>
> It is
>
> @deffn
> @end deffn
>
> Or maybe
> @deffn Command
> @end deffn

My understanding of the manual is that this is bad usage.  So in my
opinion, makeinfo should warn here.

Oleg

[Karl Berry]

    > @deffn
    > @end deffn
    >
    > Or maybe
    > @deffn Command
    > @end deffn

    My understanding of the manual is that this is bad usage.  So in my
    opinion, makeinfo should warn here.

I agree.

[Patrice Dumas]

On Wed, Aug 12, 2009 at 05:06:20PM -0500, Karl Berry wrote:

>     > @deffn
>     > @end deffn
>     >
>     > Or maybe
>     > @deffn Command
>     > @end deffn
>
>     My understanding of the manual is that this is bad usage.  So in my
>     opinion, makeinfo should warn here.
>
> I agree.

Ok, nothing to change, then...

--
Pat

[Karl Berry]

(More mail from August.)

    I remember than we agreed that @images paths were relative to the
    result file. So, to have paths right, @image should be searched for in
    this directory.

    > My inclination is to say that searching the destination directory for
    > any kind of input file, image or otherwise, would just have great

    For input files, indeed it has potential for confusion, but for
    images, it seems to me to be rather logical. The issue with
    images is that they aren't only something that is inputed in a

For one thing, how do you know what the output directory is?

So if an input document foo.texi contains @image{foo}, then when
foo.texi is processed with makeinfo --html, foo.png/etc. will be
searched for in both foo.texi's directory (fine), anything specified
with -I (fine), and in $(htmldir)?

Somehow I just can't picture it.  

    manual, they are also part of the final outputed manual (at least
    in html).

Yes, that's true.  (Images can also be separate files in Info output.)
But I'm not sure that means we should be searching the output directory
at input time.

[Karl Berry]

(More mail from August.)

    I remember than we agreed that @images paths were relative to the
    result file. So, to have paths right, @image should be searched for in
    this directory.

    > My inclination is to say that searching the destination directory for
    > any kind of input file, image or otherwise, would just have great

    For input files, indeed it has potential for confusion, but for
    images, it seems to me to be rather logical. The issue with
    images is that they aren't only something that is inputed in a

For one thing, how do you know what the output directory is?

So if an input document foo.texi contains @image{foo}, then when
foo.texi is processed with makeinfo --html, foo.png/etc. will be
searched for in both foo.texi's directory (fine), anything specified
with -I (fine), and in $(htmldir)?

Somehow I just can't picture it.  

    manual, they are also part of the final outputed manual (at least
    in html).

Yes, that's true.  (Images can also be separate files in Info output.)
But I'm not sure that means we should be searching the output directory
at input time.

[Patrice Dumas]

On Mon, Oct 26, 2009 at 07:58:52PM -0500, Karl Berry wrote:
>
> For one thing, how do you know what the output directory is?

How could I not know it? I have to output results files in it?
It is found assuming that directory separator is /, so it could not
be portable, though.

> Yes, that's true.  (Images can also be separate files in Info output.)
> But I'm not sure that means we should be searching the output directory
> at input time.

As I said then, I also agree with that. Even if it makes sense, it is
too much magic to search in output directory, user should add it with -I
if needed.

--
Pat

[Karl Berry]

    > For one thing, how do you know what the output directory is?

    How could I not know it? I have to output results files in it?

Oh.  That output directory :).  But the makeinfo -o directory is
unlikely to be where the HTML files are actually installed in the end.

    Even if it makes sense, it is too much magic to search in output
    directory, user should add it with -I if needed.

Ok, good.  It wasn't clear to me from the earlier message whether the
"output directory" was being searched or not.

Thanks,
k

[Karl Berry]

(Yet more old mail.)

    >     * the code of xml.c in makeinfo shows specific treatement of & in
    >       definition arguments. Could you please explain what it is meant to
    >       be?
    No answer, here?

Did we ever discuss this?  Anyway, I believe it's a specific hack for Elisp:
(defun foo arg1 &optional opt1 &rest r
==
@defun foo arg1 &optional opt1 &rest r

I guess Philippe (or whomever) decided to translate that as <defparam>.

Personally, I'm not sure it's possible to rationally parse the arguments
to @defun.

    Should @top be used if there is none of
    @settitle @title @shorttitlepage @titlefont (I don't know)?

Sounds fine to me.

    and if there is no title should there be a warning if producing html
    (I believe so)?

Sounds fine to me.

Thanks,
k

[Patrice Dumas]

On Wed, Oct 28, 2009 at 12:53:50PM -0500, Karl Berry wrote:
>
> Did we ever discuss this?  Anyway, I believe it's a specific hack for Elisp:

Yes, we did. I didn't found any effect of & in my tests, so I didn't
treat is especially.

The other issues were solved too.

--
Pat