[bug #53243] regression: .hy not working in latest groff build

[Dave]

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

Yes, it works now.  Thank you!

___

Reply to this item at:

  

___
  Message sent via/by Savannah
  http://savannah.gnu.org/


___
bug-groff mailing list
bug-groff@gnu.org
https://lists.gnu.org/mailman/listinfo/bug-groff

Re: [groff] groff as the basis for comprehensive documentation?

[Nate Bargmann]

* On 2018 18 Apr 19:30 -0500, Ingo Schwarze wrote:
> Hi Nate,
> 
> Nate Bargmann wrote on Wed, Apr 18, 2018 at 06:52:44PM -0500:
> 
> > After reading a bit about mdoc,
> 
> I'm sure here you mean mandoc(1), the program, not mdoc(7), the
> markup language.

Yes, indeed.
> 
> > I was disappointed that unlike "man" that I find on Slackware or
> > Debian, I had to add an uninstalled man page into the db in order
> > for "mandoc" to open it.  Perhaps I missed an option, but the "man"
> > I'm familiar with is capable of opening a file simply by giving it
> > a path name.
> 
> That is non-standard behaviour even on GNU/Linux:
> 
>$ lsb_release -d
>   Description:Debian GNU/Linux 8.10 (jessie)
>$ dpkg-query -l man-db | tail -n 1
>   ii  man-db 2.7.0.2-5i386 on-line manual pager
>$ ls *.1
>   apropos.1  demandoc.1  man.1  man.options.1  mandoc.1  soelim.1
>$ man apropos.1# the man-db man(1) implementation
>   No manual entry for apropos.1
>$ ./Bin/man apropos.1  # the mandoc man(1) implementation
>   man: No entry for apropos.1 in the manual.
> 
> However:
> 
>$ man -l apropos.1 | grep 'search manual'
>  apropos, whatis - search manual page databases
>$ ./Bin/man -l apropos.1 | grep 'search manual'
>  apropos, whatis - search manual page databases

Well, I am doing a simple 'man ./foo.1' in the project directory and I
get the page displayed through less.  Been doing it that way for years
on Debian and now Slackware.

The default man in Slackware complains there is no option '-l' available
and gives me the usage screen.

> As a matter of fact, the inspiration for the -l option came from
> Linux, and the person who asked me to implement it in mandoc several
> years ago was an Alpine Linux developer.  Classical BSD man(1) did
> not have the -l option, but i agree that it is useful, and i use it
> many times every day.
>
> I think it is good that the '-l' ("local") option is required when
> giving a file name in the local directory, or an absolute path.
> The program has many different ways to specify which page to display:
> 
>  * by full page name as in man(1)
>  * by whole word search as in whatis(1) = man -f
>  * by substring or regexp search as in apropos(1) = man -k
>  * by file name as in man -l

I now looked at mandoc's man(1) page again and the '-l' option is
explained as you have used it here.  Somehow I missed that the other day
and had tried '-m' and '-M' to no avail.  Then I managed to construct a
directory local .db and could read my test file.

Perhaps an example would be a benefit.  I often check the EXAMPLE
section of pages as I'm the sort that gets more out of working example
than even a good explanation.

> With so many different semantics of a command line, guessing
> what the user meant will only cause confusion.

One thing I have learned, a user will try all sorts of permutations the
developer never considered!  A user will also read the manual very
differently than the developer or its author.  I try to keep these
points in mind as I work with the project.

> Besides, with the mandoc implementation of man(1), it is not
> absolutely required to update the database even after installing a
> new page into /usr/share/man/.  The man(1) program will find the
> new page at once even if it is not yet in the database - but of
> course, apropos(1) cannot find it, so always keeping the database
> up to date still makes sense.  A good package manager will do that
> for you, so it is no hassle.

Thanks, Ingo.

I'll admit to not being a 'man' power user.  I use it to quickly pull up
a page and don't even think of 'apropos' or the other command line
options.  Like a lot of us, I'm probably lazy in all the wrong areas.
;-)

I know we're veering off topic for this list.

- Nate

-- 

"The optimist proclaims that we live in the best of all
possible worlds.  The pessimist fears this is true."

Web: http://www.n0nb.us  GPG key: D55A8819  GitHub: N0NB


signature.asc
Description: PGP signature

Re: [groff] groff as the basis for comprehensive documentation?

[Ingo Schwarze]

Hi Nate,

Nate Bargmann wrote on Wed, Apr 18, 2018 at 06:52:44PM -0500:

> After reading a bit about mdoc,

I'm sure here you mean mandoc(1), the program, not mdoc(7), the
markup language.

> I was disappointed that unlike "man" that I find on Slackware or
> Debian, I had to add an uninstalled man page into the db in order
> for "mandoc" to open it.  Perhaps I missed an option, but the "man"
> I'm familiar with is capable of opening a file simply by giving it
> a path name.

That is non-standard behaviour even on GNU/Linux:

   $ lsb_release -d
  Description:Debian GNU/Linux 8.10 (jessie)
   $ dpkg-query -l man-db | tail -n 1
  ii  man-db 2.7.0.2-5i386 on-line manual pager
   $ ls *.1
  apropos.1  demandoc.1  man.1  man.options.1  mandoc.1  soelim.1
   $ man apropos.1# the man-db man(1) implementation
  No manual entry for apropos.1
   $ ./Bin/man apropos.1  # the mandoc man(1) implementation
  man: No entry for apropos.1 in the manual.

However:

   $ man -l apropos.1 | grep 'search manual'
 apropos, whatis - search manual page databases
   $ ./Bin/man -l apropos.1 | grep 'search manual'
 apropos, whatis - search manual page databases

As a matter of fact, the inspiration for the -l option came from
Linux, and the person who asked me to implement it in mandoc several
years ago was an Alpine Linux developer.  Classical BSD man(1) did
not have the -l option, but i agree that it is useful, and i use it
many times every day.

I think it is good that the '-l' ("local") option is required when
giving a file name in the local directory, or an absolute path.
The program has many different ways to specify which page to display:

 * by full page name as in man(1)
 * by whole word search as in whatis(1) = man -f
 * by substring or regexp search as in apropos(1) = man -k
 * by file name as in man -l

With so many different semantics of a command line, guessing
what the user meant will only cause confusion.


Besides, with the mandoc implementation of man(1), it is not
absolutely required to update the database even after installing a
new page into /usr/share/man/.  The man(1) program will find the
new page at once even if it is not yet in the database - but of
course, apropos(1) cannot find it, so always keeping the database
up to date still makes sense.  A good package manager will do that
for you, so it is no hassle.

Yours,
  Ingo

Re: [groff] groff as the basis for comprehensive documentation?

[Nate Bargmann]

* On 2018 18 Apr 12:26 -0500, Larry Kollar wrote:
> At work, we’re in the first stages of moving our writers over to a
> DITA-based CMS.

Well, you forced me to look up DITA.  ;-)

> Ingo’s mandoc solution is a good way to produce text/HTML output, and you
> can use groff for PDF. The only thing I’d take issue with is his assertion 
> that
> -mdoc is easier to write than legacy -man. No doubt that -mdoc’s semantic
> markup adds value, but I’ve always had trouble getting my head around the
> syntax.

After reading a bit about mdoc, I was disappointed that unlike "man"
that I find on Slackware or Debian, I had to add an uninstalled man page
into the db in order for "mandoc" to open it.  Perhaps I missed an
option, but the "man" I'm familiar with is capable of opening a file
simply by giving it a path name.  Fortunately, the "man" currently in
Slackware does read an mdoc formatted page just fine, so mdoc formatted
pages are not on island.

Another thing I have to consider is the ability of others to submit
patches based on familiarity.  As arcane as it is, most contributors
seem to have bumped against classic man macros but I think jumping to
mdoc would leave me as the sole maintainer.  Consequently, the project
will use the man macros until more distributions make mdoc the default.
Note that I'm not arguing against it, just saying that right now it
doesn't appear to be the right tool for us.

Deri's effort is quite in line with what I think I am looking for.
Using the .texi files for an introduction and even starting each
reference chapter and then including the man pages to make up the
references without duplicating the work, would seem to be an ideal way
to meld the strengths of each document system.

With that in mind, I'll continue to work on the man pages.  Thanks for
the good discussion thus far.

- Nate

-- 

"The optimist proclaims that we live in the best of all
possible worlds.  The pessimist fears this is true."

Web: http://www.n0nb.us  GPG key: D55A8819  GitHub: N0NB


signature.asc
Description: PGP signature

[bug #53664] an-old.tmac: .TP causes wrong formatting with a long tag

[Ingo Schwarze]

Update of bug #53664 (project groff):

Severity:  3 - Normal => 2 - Minor  
  Status:None => Need Info  

___

Follow-up Comment #1:

What exactly is wrong here?
What exactly do you suggest the groff should print?

Groff and mandoc produce identical output, and it looks completely correct to
me.

Sure, the word "initialization" exceeds the right margin.
But that can't be helped with such an insanely wide indentation: garbage in,
garbage out!
Exceeding the right margin is normal groff behaviour when the line cannot be
broken.

Is any project member willing to provide an "OK" to close this ticket as
invalid?

___

Reply to this item at:

  

___
  Message sent via/by Savannah
  http://savannah.gnu.org/


___
bug-groff mailing list
bug-groff@gnu.org
https://lists.gnu.org/mailman/listinfo/bug-groff

[bug #53674] [PATCH] pdfpic.tmac: Neutralize extra ".."

[Ingo Schwarze]

Update of bug #53674 (project groff):

Severity:  3 - Normal => 2 - Minor  
  Status:None => Fixed  
 Assigned to:None => schwarze   
 Open/Closed:Open => Closed 

___

Follow-up Comment #1:

Obviously, if a file contains two consecutive, identical lines,
it doesn't matter which one is removed.
I deleted the excess line, thanks for noticing.

___

Reply to this item at:

  

___
  Message sent via/by Savannah
  http://savannah.gnu.org/


___
bug-groff mailing list
bug-groff@gnu.org
https://lists.gnu.org/mailman/listinfo/bug-groff

[groff] 01/01: pdfpic.tmac: delete excess ".." line

[Ingo Schwarze]

schwarze pushed a commit to branch master
in repository groff.

commit bf01a970db9b1505fc6c2ceef2ed9050aa6b40d0
Author: Ingo Schwarze 
Date:   Wed Apr 18 22:18:48 2018 +0200

pdfpic.tmac: delete excess ".." line

It was inadvertently introduced in the previous commit.
Reported by Bjarni Ingi Gislason.
---
 tmac/pdfpic.tmac | 1 -
 1 file changed, 1 deletion(-)

diff --git a/tmac/pdfpic.tmac b/tmac/pdfpic.tmac
index c3859bf..0400c1c 100644
--- a/tmac/pdfpic.tmac
+++ b/tmac/pdfpic.tmac
@@ -142,7 +142,6 @@ sed -e 's/Page *size: *\\([[:digit:].]*\\) *x 
*\\([[:digit:].]*\\).*$/\
 .sp \\n[pdf-desht]u
 .  \}
 ..
-..
 .
 .cp \n[_C]
 .

___
Groff-commit mailing list
Groff-commit@gnu.org
https://lists.gnu.org/mailman/listinfo/groff-commit

Re: [groff] groff as the basis for comprehensive documentation?

[Larry Kollar]

Nate Bargmann  wrote:

> I have long been involved with a project that has lacked good
> documentation for nearly all of its existence.  We've had documentation,
> but it isn't in a good format for generating man, HTML, or PDF versions.
> 
> Long ago I started with Docbook and then that got to a point no one else
> would touch it and I didn't want to either.  XML was the "wave of the
> future" but I didn't jump on that wagon.  …

At work, we’re in the first stages of moving our writers over to a DITA-based 
CMS.
It’s horribly complex (and I should know, I’m in the vanguard), but does have a
pretty good way of producing both good PDF and decent HTML. I love when
people go “ooh, topic-based, shiny!” and I point out manpages have been around
for decades. :-D

BUT… if you want manpages, write manpages. I have not found anything yet
that does a good job of automatically creating manpages from any other kind
of format. DITA’s reference topic might be a reasonable basis for a conversion,
but writing that descriptive title is still beyond any AI. It has to look 
natural to a
human reader, while containing all the keywords needed to find it in a search
(thus being both content and metadata).

Ingo’s mandoc solution is a good way to produce text/HTML output, and you
can use groff for PDF. The only thing I’d take issue with is his assertion that
-mdoc is easier to write than legacy -man. No doubt that -mdoc’s semantic
markup adds value, but I’ve always had trouble getting my head around the
syntax.

Larry

[groff] 01/01: groff_man(7): ".IP", Use "first" instead of "second"

[Ingo Schwarze]

schwarze pushed a commit to branch master
in repository groff.

commit 669cc6e46153a28aa71d6ea59cbdf929000d2604
Author: Bjarni Ingi Gislason 
Date:   Wed Apr 18 02:44:48 2018 +

groff_man(7): ".IP", Use "first" instead of "second"

The correct word is used in the file "groff.info-1" (info groff).
---
 tmac/groff_man.7.man | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/tmac/groff_man.7.man b/tmac/groff_man.7.man
index a72e955..b85c6b2 100644
--- a/tmac/groff_man.7.man
+++ b/tmac/groff_man.7.man
@@ -338,7 +338,7 @@ to its default values.
 .IP
 To start an indented paragraph with a particular indentation but
 without a designator, use \[oq]""\[cq] (two doublequotes) as the
-second argument.
+first argument.
 .
 .
 .IP

___
Groff-commit mailing list
Groff-commit@gnu.org
https://lists.gnu.org/mailman/listinfo/groff-commit

[bug #53686] [PATCH] groff_man.7.man: ".IP", Use "first" instead of "second"

[Ingo Schwarze]

Update of bug #53686 (project groff):

Category:None => Macro - man
Severity:  3 - Normal => 2 - Minor  
  Status:None => Fixed  
 Assigned to:None => schwarze   
 Open/Closed:Open => Closed 


___

Reply to this item at:

  

___
  Message sent via/by Savannah
  http://savannah.gnu.org/


___
bug-groff mailing list
bug-groff@gnu.org
https://lists.gnu.org/mailman/listinfo/bug-groff