[bug #58653] want the short mdoc(7) page that Linux man-pages used to ship

[INVALID.NOREPLY]

Follow-up Comment #11, bug #58653 (project groff):

[comment #10 comment #10:]
> It looks like nobody has the desire to resolve this as the submitter
requested.
> 
> I would point out, however, that since last updating this ticket over a year
ago, I have significantly revised the opening sections of the _groff_mdoc_(7)
man page (and some other spots within it).

Thank you. I appreciate your improvements, but you may as well close this bug.
My request for a brief quick reference guide does not appear to fit well with
the groff project's current goals.


___

Reply to this item at:

  

___
Message sent via Savannah
https://savannah.gnu.org/

[bug #61043] potential integer overflow vulnerability in src/preproc/grn/hdb.cpp

[INVALID.NOREPLY]

URL:
  

 Summary: potential integer overflow vulnerability in
src/preproc/grn/hdb.cpp
 Project: GNU troff
Submitted by: eqkws
Submitted on: Sun 15 Aug 2021 06:03:08 AM UTC
Category: None
Severity: 3 - Normal
  Item Group: None
  Status: None
 Privacy: Private
 Assigned to: None
 Open/Closed: Open
 Discussion Lock: Any
 Planned Release: None

___

Details:

Hi, I found some integer overflow bug in the source code of groff.

In src/preproc/grn/hdb.cpp:189,

189 (void) fscanf(file, "%d", );/* text length */
190 (void) getc(file);  /* eat blank */
191 txt = (char *) malloc((unsigned) len + 1);

The program reads the value of len from an input file and calls malloc with
len + 1.

If a maliciously crafted input that sets len to -1 is given, it will cause an
integer overflow, and allocation with 0 leads to buggy behavior like denial of
service.

Thank you.




___

Reply to this item at:

  

___
  Message sent via Savannah
  https://savannah.gnu.org/

[bug #58653] Please add back in the mdoc(7) manual

[INVALID.NOREPLY]

Follow-up Comment #6, bug #58653 (project groff):

[comment #5 comment #5:]
> 
> > This mandoc mdoc(7) you are speaking of,
> > is it part of groff? I don't see it.
> 
> No it isn't.
> I already posted the hyperlink: https://man.openbsd.org/mdoc.7
> It is part of mandoc.

Please pardon my ignorance. I had thought you were linking to the mdoc
documentation that comes with BSD. Is that not right? 


> What i oppose is adding another manual page for the same thing.

Clearly, as someone who has contributed to groff for a long time, Ingo, you
should have more say about the documentation than someone like me who has just
begun. I don't think I can convince you that a quick reference guide is not
redundant, so I will drop it.

I do think it is unfortunate that people who use groff on non-BSD systems are
left poorer, without even a pointer to better documentation. 

___

Reply to this item at:

  

___
  Message sent via Savannah
  https://savannah.gnu.org/

[bug #58653] Please add back in the mdoc(7) manual

[INVALID.NOREPLY]

Follow-up Comment #4, bug #58653 (project groff):

[comment #3 comment #3:]
> You say "but beginners need something simpler".  I contest that.  It's not
because i'm an expert on mdoc(7).  When learning a completely new language
totally from scratch, i typically go for the formal standard / formal language
definition (or the reference manual if there is no completely formal
document), and certainly not for the user manual or tutorial, which usually is
a total waste of time even during the first two or three hours of learning.

May I suggest that, perhaps, you are a bit of an exception? There are many
different kinds of minds out there. Even if you find user manuals to be a
waste of time, some of us do not.


> Just train your reading skills to quickly extract the information you need
from a precise, concise text without reading all the words.

Perhaps part of the problem here is that we are talking about different
things. You mention extracting information from formal specifications, but I'm
starting out from the meta-question "Do I even want to learn this?"

Good documentation lets people know right away what the cost of learning will
be and what the benefits are. For example, mdoc(7) told me the benefit
(semantic markup) and then showed that using it would not be complicated. 


> Why do you think we spent the time to get the horrible document
exterminated?  

Honestly, I had thought the problem was that it was maintained by the Linux
kernel folks and the groff team wanted something that they could keep
up-to-date. "Exterminating" the quick reference guide without replacement
seems a bit extreme.


> [...] the high-level "what is this all about" stuff useful for beginners is
easier to find in mandoc mdoc(7) than in groff_mdoc(7).  Certainly no need for
a third.

This mandoc mdoc(7) you are speaking of, is it part of groff? I don't see it.
I filed this bug report to improve the documentation for groff, but perhaps it
just needs to be made easier to find.


___

Reply to this item at:

  

___
  Message sent via Savannah
  https://savannah.gnu.org/

[bug #58653] Please add back in the mdoc(7) manual

[INVALID.NOREPLY]

Follow-up Comment #2, bug #58653 (project groff):

[comment #1 comment #1:]
> I *VERY* strongly oppose this idea.

Thank you, Ingo, although I do wish you had mentioned this on the mailing list
when I first brought it up or at the point when someone else suggested that
the groff project needs to have a bug report on it.

Ingo, at your request, the Linux man pages dropped mdoc(7) last year. The fact
that BSD has good documentation doesn't alleviate the need for GNU/Linux
systems to also have complete and useful documentation. It is now up to the
groff project to make sure that happens.


> Documentation ought to be correct, complete, concise, and easy to find,
which implies all in one place.

Trying to balance competing goals, such as "complete" and "easy to
understand", in a single document is difficult, sometimes impossible. When it
does happen, it takes a lot of time and effort to get right. Also, it's a bear
to maintain as inevitably changes accrue that throw it out of balance.

It is much less work to have separate documents. One of them, groff_mdoc(7),
can prioritize being correct and complete. The other, mdoc(7), can focus on
being concise and easy to learn from. And that's what GNU/Linux had until
mdoc(7) was dropped.


> It is even a terrible starting point for working on something better.

Experts are always disappointed by any quick reference guide: "it is
incomplete and wrong!" But, that's mainly because it has been optimized for
understandability to a more general audience: people like me who are *not*
already experts. Such tutorials are top-loaded with broad brush strokes giving
general use and "quick start for the impatient" type of information. Then they
go on to the most useful features and work their way down. Nitty gritty
details are pushed to the back, if covered at all.

For example, from reading mdoc(7), I knew very quickly what the point of mdoc
was, where to find the full documentation (groff_mdoc(7)), and even the
minimal commands needed to create a valid mdoc manual page. I could see that I
wouldn't have to invest much time for this package to be useful to me.

Whereas, reading that far in groff_mdoc(7), my eyes had glazed over. Does one
have to understand "troff idiosyncracies" to use this package? It's not clear
from the document, but that's because it has a different purpose: if I need to
understand mdoc in more detail, I can come back to it.


> One reference manual is enough.

Yes, for people who already know mdoc. For people getting started or needing
to brush up, a quick reference guide serves them better. If you're writing for
humans, the documentation isn't complete unless it includes an approachable
guide for new users.

Documentation is not like computer programming where we want to do things in
exactly one place. Different people find different forms of documentation
helpful and repetition phrased in alternate ways is actually better. It is not
harmful to have more than one document, even if they get out of sync, as long
as the informal guide explicitly links to the complete reference. (Note that
mdoc(7) starts out by referencing groff_mdoc(7).)


> If groff developers think groff_mdoc(7) needs an overview before diving into
the specifics, i can copy the "MACRO OVERVIEW" section from
>   https://man.openbsd.org/mdoc#MACRO_OVERVIEW

Ingo, please do not take offense, but I think perhaps you may be too expert. I
say this with great respect: The fact that you don't see the point of mdoc(7),
which was so helpful to a troff neophyte like me, raises the question of
whether you are the right person to make groff's documentation more user
friendly.

I am full of humility and admiration for the work Ingo and all the groff
devlopers have put in over the years. Even if you reject this bug, I thank
you.

--b9


___

Reply to this item at:

  

___
  Message sent via Savannah
  https://savannah.gnu.org/

[bug #58653] Please add back in the mdoc(7) manual

[INVALID.NOREPLY]

URL:
  

 Summary: Please add back in the mdoc(7) manual
 Project: GNU troff
Submitted by: hackerb9
Submitted on: Wed 24 Jun 2020 10:13:31 PM UTC
Category: Macro - mdoc
Severity: 3 - Normal
  Item Group: Documentation
  Status: None
 Privacy: Public
 Assigned to: None
 Open/Closed: Open
 Discussion Lock: Any
 Planned Release: None

___

Details:

According to Ingo Schwarze on the groff mailing list, the groff
project recently convinced the Linux man pages project to remove their
mdoc(7) manual as it was outdated by a few decades. 

However, the groff project lacks anything equivalent to mdoc(7).

Ingo suggested I try mandoc.bsd.lv, but I found it more cryptic and
less helpful.

Yes, there is a man page for groff_mdoc(7), but it is a "complete
reference" which is rather difficult for a beginner to get started
using mdoc. In contrast, mdoc(7) from the Linux man pages was a quick
reference on the macro names and their meanings, laid out in a logical
fashion. At the top, mdoc(7) informs the reader to check groff_mdoc(7)
for the nitty gritty.

groff_mdoc(7) appears to have been based upon mdoc.samples(7) which
was written as a companion to mdoc(7). Although groff_mdoc(7) removed
all references to mdoc(7), it does not stand alone well. As somone new
to the world of troff, I found mdoc(7) to be necessary when I
attempted my first serious man pages. If I had had only groff_mdoc(7)
available, I would have given up.

Please import the old mdoc(7) file into the groff project so that it
can become available on all GNU/Linux machines once again. Please do
not wait to update it before importing. Even outdated, it is extremely
useful and mostly correct. Once in Savannah, it can be iteratively
improved via bug reports.

The mdoc(7) file can be viewed online here:

  https://man7.org/linux/man-pages/man7/mdoc.7.html

And the troff can be found here:

 
https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/man7/mdoc.7?id=6474f351fd8ac68e6e0c8820bb8926c6b9e3ec97

Thanks!





___

Reply to this item at:

  

___
  Message sent via Savannah
  https://savannah.gnu.org/