octave-maintainers
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Info documentation indents


From: Rik
Subject: Info documentation indents
Date: Mon, 06 Feb 2012 07:48:06 -0800

2/6/12

John,

The Info documentation that appears at the terminal with 'help XXX' is off
by one column for ALL of the C++ source files.  The issue is in
__makeinfo__.m where there is the following search&replace on the help text:

--- code ---
## It seems like makeinfo sometimes gets angry if the first character
## on a line is a space, so we remove these.
text = strrep (text, "\n ", "\n");
--- end code ---

This is only appropriate for the m-files, where the convention is to begin
each line with '## '.  To see it in action try 'help for' which gives the
following.

--- code ---
 -- Keyword:  for I = RANGE
     Begin a for loop.

          for i = 1:10
           i
          endfor
--- end code ---

Note that there is only one indentation space for the body of the for loop
even though the indentation is correct in the C++ sources.

--- code ---
@example\n\
@group\n\
for i = 1:10\n\
  i\n\
endfor\n\
@end group\n\
@end example\n\
--- end code ---

I've investigated a little and the comment about Texinfo getting angry is
not specific enough.  The problem is not, in general, having a space at the
beginning of a line.  Rather, it is not having the command '@end tex' start
at the beginning of a line.  After entering raw Tex mode, Texinfo cannot
easily determine where a raw block ends.  In this *one* case we need to
ensure that '@end tex' appears by itself at the start of a line.

I'm proposing the following patch for __makeinfo__.m

--- code ---
## Formatting in m-files has an extra space at the beginning of every line.
## Remove these unwanted spaces if present.  First text char is "\n" delim.
if (text(2) == " ")
  text = strrep (text, "\n ", "\n");
endif
## Texinfo crashes if @end tex does not appear first on the line.
text = regexprep (text, '^ address@hidden tex', '@end tex', 'lineanchors');
--- end code ---

The reason for the e-mail is that I would like to apply this to stable A)
because it is a documentation-only patch and B) because I would like to be
able to apply further documentation patches to stable.

If this patch is applied to the devolopment branch, then it will make
applying help patches to any of the C++ source code on stable difficult. 
The two branches will be out of sync because one will require an extra
space in every docstring; merging will be a nasty exercise.  In order to
avoid that I would simply commit all documentation patches to the
development branch.

So, is it acceptable to make this change on the stable branch and then
update any C++ docstrings that are now off by 1 the other way?

--Rik



reply via email to

[Prev in Thread] Current Thread [Next in Thread]