Re: @ref without page numbers
I agree with your evaluation Patrice. > Sent: Saturday, October 24, 2020 at 1:56 AM > From: "Patrice Dumas" > To: "Karl Berry" > Cc: dim...@gmx.com, help-texinfo@gnu.org > Subject: Re: @ref without page numbers > > On Fri, Oct 23, 2020 at 04:41:30PM -0600, Karl Berry wrote: > > Christopher, if you want to write full technical documents with lots of > > references, math, etc., why don't you just use LaTeX? Texinfo is not > > designed for this. Trying to shoehorn it to fit seems fraught with problems. > > LaTeX is not very practical to write program documentation. Texinfo is > not so good at math and bibliography. However, when you need both, for > instance when you write a manual for a program dealing with mathematics, > I find Texinfo with tex4ht or latex2html and now mathjax to be better > compromise than LaTeX as LaTeX is very poor for program documentation. > The html obtained, for instance is much more suitable when going through > Texinfo. > > -- > Pat >
Re: @ref without page numbers
On Fri, Oct 23, 2020 at 04:41:30PM -0600, Karl Berry wrote: > Christopher, if you want to write full technical documents with lots of > references, math, etc., why don't you just use LaTeX? Texinfo is not > designed for this. Trying to shoehorn it to fit seems fraught with problems. LaTeX is not very practical to write program documentation. Texinfo is not so good at math and bibliography. However, when you need both, for instance when you write a manual for a program dealing with mathematics, I find Texinfo with tex4ht or latex2html and now mathjax to be better compromise than LaTeX as LaTeX is very poor for program documentation. The html obtained, for instance is much more suitable when going through Texinfo. -- Pat
Re: @ref without page numbers
Because my package requires them. I managed to get a decent bibliography good enough for release. If some humps are smoothed, I can see that texinfo would have great capability. For instance, having math in html produced much interest. Gavin has also got to some small page sizes as well, which makes texinfo very attractive. Stallman has written his book in texinfo. I also found it much better than you envisage. Regards Christopher - Christopher Dimech Chief Administrator - Naiad Informatics - GNU Project (Geocomputation) - Geophysical Simulation - Geological Subsurface Mapping - Disaster Preparedness and Mitigation - Natural Resource Exploration and Production - Free Software Advocacy > Sent: Saturday, October 24, 2020 at 12:41 AM > From: "Karl Berry" > To: dim...@gmx.com > Cc: gavinsmith0...@gmail.com, help-texinfo@gnu.org > Subject: Re: @ref without page numbers > > Christopher, if you want to write full technical documents with lots of > references, math, etc., why don't you just use LaTeX? Texinfo is not > designed for this. Trying to shoehorn it to fit seems fraught with problems. > > Using @ref for bibliography entries seems like a problem in the first > place. Texinfo doesn't have any real bibliography support. All the > workarounds in the world are not going to produce robust output or > processing. > > Just my unasked-for $.002, sorry, > Karl >
Re: @ref without page numbers
Christopher, if you want to write full technical documents with lots of references, math, etc., why don't you just use LaTeX? Texinfo is not designed for this. Trying to shoehorn it to fit seems fraught with problems. Using @ref for bibliography entries seems like a problem in the first place. Texinfo doesn't have any real bibliography support. All the workarounds in the world are not going to produce robust output or processing. Just my unasked-for $.002, sorry, Karl
Re: @ref without page numbers
There might be no precedent, yet I have found a use case to highlight
the point in one of my mathematical documents.
Look at this
[Schimmel & Gallart (2007)], page 29, [Bensen, Ritzwoller et al. (2007)],
page 27, [Ventosa et al. (2017)], page 30,
and compare with this
[Schimmel & Gallart (2007)]^p29, [Bensen, Ritzwoller et al. (2007)]^p27,
[Ventosa et al. (2017)]^p30,
We can use @sup{pN} to remove the longer (full) page representation.
I had passed the document around and the full output was deemed problematic.
The problem not only occurs with printed but also with pdf. And as you pointed
out the page number is required if the document is printed, and we can also
solve
the readability problem that occurs with multiple @ref next to each other.
Was not aware that you tackled the task of removing the page number completely.
But, I am unsure how I can introduce your modification in my file to test it.
Nevertheless, my alternative brief page numbering would resolve the readability
problem pointed out to me.
Regards
Christopher
> Sent: Friday, October 23, 2020 at 11:44 PM
> From: "Gavin Smith"
> To: "Christopher Dimech"
> Cc: "help-texinfo gnu"
> Subject: Re: @ref without page numbers
>
> On Fri, Oct 23, 2020 at 10:40:52PM +0200, Christopher Dimech wrote:
> > Dear Gavin,
> >
> > You are quite right, if the manual is printed, one needs the page numbers.
> >
> > I would be satisfied with an option in which the page number is printed
> > as a superscript @sup{page-no} (similar to footnote numbers) next to the
> > closing square bracket.
> >
> > That is, from this
> >
> > Section 1.13 [Intactv-Function], page 11,
> >
> > to this
> >
> > Section 1.13 [Intactv-Function]@sup{11},
> >
> > The would solve the problem, yet keep requirements intact.
> >
> > Regards
> > Christopher
>
> There's no precedent for this - this looks like a footnote reference.
> Would it not be simpler to miss out the page number, as in my patch
> here?
>
> https://lists.gnu.org/archive/html/bug-texinfo/2016-11/msg00048.html
>
Re: @ref without page numbers
On Fri, Oct 23, 2020 at 10:40:52PM +0200, Christopher Dimech wrote:
> Dear Gavin,
>
> You are quite right, if the manual is printed, one needs the page numbers.
>
> I would be satisfied with an option in which the page number is printed
> as a superscript @sup{page-no} (similar to footnote numbers) next to the
> closing square bracket.
>
> That is, from this
>
> Section 1.13 [Intactv-Function], page 11,
>
> to this
>
> Section 1.13 [Intactv-Function]@sup{11},
>
> The would solve the problem, yet keep requirements intact.
>
> Regards
> Christopher
There's no precedent for this - this looks like a footnote reference.
Would it not be simpler to miss out the page number, as in my patch
here?
https://lists.gnu.org/archive/html/bug-texinfo/2016-11/msg00048.html
Re: @ref without page numbers
Pdf are very important in business settings, and because Texinfo allows inclusion of mathematical expression (through @math, @tex), the pdf output is very useful. Regards Christopher > Sent: Friday, October 23, 2020 at 10:05 PM > From: "Gavin Smith" > To: "Christopher Dimech" > Cc: "help-texinfo gnu" > Subject: Re: @ref without page numbers > > On Fri, Oct 23, 2020 at 09:18:12PM +0200, Christopher Dimech wrote: > > I could not follow it very well. > > > > My problem occurs in pdf output. How is the page number important, is > > there notion > > of page number in other formats, not just only on pdf? How are links and > > page numbers > > related? Can one do anything for the pdf case only? > > If the manual is printed on paper, the page number is needed for the > reader to look up the cross-reference. > > This issue has been discussed in the past: > > https://lists.gnu.org/archive/html/bug-texinfo/2016-11/msg00029.html > https://lists.gnu.org/archive/html/bug-texinfo/2016-11/msg00036.html > > (BTW the discussion containing that message goes into a lot of other > extraneous matters - please try and keep discussion germane to the > issue at hand.) > >
Re: @ref without page numbers
Dear Gavin,
You are quite right, if the manual is printed, one needs the page numbers.
I would be satisfied with an option in which the page number is printed
as a superscript @sup{page-no} (similar to footnote numbers) next to the
closing square bracket.
That is, from this
Section 1.13 [Intactv-Function], page 11,
to this
Section 1.13 [Intactv-Function]@sup{11},
The would solve the problem, yet keep requirements intact.
Regards
Christopher
> Sent: Friday, October 23, 2020 at 10:05 PM
> From: "Gavin Smith"
> To: "Christopher Dimech"
> Cc: "help-texinfo gnu"
> Subject: Re: @ref without page numbers
>
> On Fri, Oct 23, 2020 at 09:18:12PM +0200, Christopher Dimech wrote:
> > I could not follow it very well.
> >
> > My problem occurs in pdf output. How is the page number important, is
> > there notion
> > of page number in other formats, not just only on pdf? How are links and
> > page numbers
> > related? Can one do anything for the pdf case only?
>
> If the manual is printed on paper, the page number is needed for the
> reader to look up the cross-reference.
>
> This issue has been discussed in the past:
>
> https://lists.gnu.org/archive/html/bug-texinfo/2016-11/msg00029.html
> https://lists.gnu.org/archive/html/bug-texinfo/2016-11/msg00036.html
>
> (BTW the discussion containing that message goes into a lot of other
> extraneous matters - please try and keep discussion germane to the
> issue at hand.)
>
>
Re: @ref without page numbers
On Fri, Oct 23, 2020 at 09:18:12PM +0200, Christopher Dimech wrote: > I could not follow it very well. > > My problem occurs in pdf output. How is the page number important, is there > notion > of page number in other formats, not just only on pdf? How are links and > page numbers > related? Can one do anything for the pdf case only? If the manual is printed on paper, the page number is needed for the reader to look up the cross-reference. This issue has been discussed in the past: https://lists.gnu.org/archive/html/bug-texinfo/2016-11/msg00029.html https://lists.gnu.org/archive/html/bug-texinfo/2016-11/msg00036.html (BTW the discussion containing that message goes into a lot of other extraneous matters - please try and keep discussion germane to the issue at hand.)
Re: @ref without page numbers
I could not follow it very well.
My problem occurs in pdf output. How is the page number important, is there
notion
of page number in other formats, not just only on pdf? How are links and page
numbers
related? Can one do anything for the pdf case only?
> Sent: Friday, October 23, 2020 at 8:42 PM
> From: "Gavin Smith"
> To: "Christopher Dimech"
> Cc: "help-texinfo gnu"
> Subject: Re: @ref without page numbers
>
> On Fri, Oct 23, 2020 at 03:42:11PM +0200, Christopher Dimech wrote:
> >
> > Although it is useful to have @ref followed by page numbers, page
> > numbers can make the text very difficult to follow when there there
> > are two or more references cluttered together, or when the same
> > reference is used (particularly when this happens on the same page).
> >
> > Are there ways to stop @ref from showing page numbers?
> >
> > Although the most important command is @ref, the same thing applies
> > to other reference commands (@xref, @pref).
> >
> > Regards
> > Christopher
>
> I wrote about this in the manual recently:
>
> https://git.savannah.gnu.org/cgit/texinfo.git/commit/?id=35f4537b19697a448d4aa36389e6f1f736905281
>
> +@item Yes, but how do I get a plain link, with no extra markup?
> +
> +You can't. Info is a plain text format that is displayed mostly as-is
> +in the viewers, and without the @samp{*note} text there would be nothing
> +to mark text as a link. Additionally, in printed output there is no
> +such thing as a plain link, as the page number of the target would have
> +to be printed somewhere.
> +
> +If you really want a plain link in HTML output without affecting other
> +output formats, you could create a macro with conditional definitions for
> +each output format.
>
Re: @ref without page numbers
On Fri, Oct 23, 2020 at 03:42:11PM +0200, Christopher Dimech wrote:
>
> Although it is useful to have @ref followed by page numbers, page
> numbers can make the text very difficult to follow when there there
> are two or more references cluttered together, or when the same
> reference is used (particularly when this happens on the same page).
>
> Are there ways to stop @ref from showing page numbers?
>
> Although the most important command is @ref, the same thing applies
> to other reference commands (@xref, @pref).
>
> Regards
> Christopher
I wrote about this in the manual recently:
https://git.savannah.gnu.org/cgit/texinfo.git/commit/?id=35f4537b19697a448d4aa36389e6f1f736905281
+@item Yes, but how do I get a plain link, with no extra markup?
+
+You can't. Info is a plain text format that is displayed mostly as-is
+in the viewers, and without the @samp{*note} text there would be nothing
+to mark text as a link. Additionally, in printed output there is no
+such thing as a plain link, as the page number of the target would have
+to be printed somewhere.
+
+If you really want a plain link in HTML output without affecting other
+output formats, you could create a macro with conditional definitions for
+each output format.
@smallverbatim
Have been playing with @quotation, @example, @display, @format, @verbatim and their small versions and found them all useful, particularly the small versions. However, a small version of @verbatim is not present. It would help to also have @smallverbatim. Regards Christopher
