perldoc INSTALL

[p5pRT]

Migrated from rt.perl.org#2424 (status was 'resolved')

Searchable as RT2424$

[p5pRT]

From Richard.Foley@m.dasa.de

FYI

While installing perl-5.6.0-RC2\, I thought I'd read the INSTALL docs\, I don't suppose many people do\, but there you have it... :-)

One or two warnings​:

root@​pc026991​:/usr/local/src/temp/perl-5.6.0-RC2 >perldoc INSTALL /usr/bin/pod2man​: bad option in paragraph 52 of INSTALL​: ``-d'' should be [CB]\<-d> /usr/bin/pod2man​: bad option in paragraph 55 of INSTALL​: ``-A'' should be [CB]\<-A> /usr/bin/pod2man​: bad option in paragraph 95 of INSTALL​: ``-d'' should be [CB]\<-d> /usr/bin/pod2man​: bad option in paragraph 231 of INSTALL​: ``-g'' should be [CB]\<-g> /usr/bin/pod2man​: bad option in paragraph 232 of INSTALL​: ``-g'' should be [CB]\<-g> /usr/bin/pod2man​: bad option in paragraph 250 of INSTALL​: ``-I'' should be [CB]\<-I> /usr/bin/pod2man​: bad option in paragraph 250 of INSTALL​: ``-L'' should be [CB]\<-L> /usr/bin/pod2man​: bad option in paragraph 255 of INSTALL​: ``-I'' should be [CB]\<-I> /usr/bin/pod2man​: bad option in paragraph 260 of INSTALL​: ``-I'' should be [CB]\<-I> /usr/bin/pod2man​: bad option in paragraph 263 of INSTALL​: ``-I'' should be [CB]\<-I> /usr/bin/pod2man​: bad option in paragraph 264 of INSTALL​: ``-L'' should be [CB]\<-L> /usr/bin/pod2man​: bad option in paragraph 272 of INSTALL​: ``-d'' should be [CB]\<-d> /usr/bin/pod2man​: bad option in paragraph 299 of INSTALL​: ``-g'' should be [CB]\<-g> /usr/bin/pod2man​: bad option in paragraph 339 of INSTALL​: ``-I'' should be [CB]\<-I> /usr/bin/pod2man​: bad option in paragraph 348 of INSTALL​: ``-B'' should be [CB]\<-B> /usr/bin/pod2man​: bad option in paragraph 402 of INSTALL​: ``-s'' should be [CB]\<-s> /usr/bin/pod2man​: bad option in paragraph 409 of INSTALL​: ``-K'' should be [CB]\<-K> /usr/bin/pod2man​: bad option in paragraph 409 of INSTALL​: ``-g'' should be [CB]\<-g>

Ciao Richard Foley

---

richard@​rfi.net 'Ciao' - shorter than 'Aufwiedersehen'

[p5pRT]

From [Unknown Contact. See original ticket]

According to Richard Foley \Richard\.Foley@&#8203;m\.dasa\.de​: :While installing perl-5.6.0-RC2\, I thought I'd read the INSTALL docs\, I :don't suppose many people do\, but there you have it... :-)

What kinds of things could be automated as a part of building a 'release'\, so that before a release the docs can be built for the various formats without error\, etc.? Perhaps a script that a) identifies all pod documentation in the release\, b) does some sort of 'lint-like check' to see if each pod is properly parseable\, and c) some sort of test to see if any doc processing for the particular platform works properly (whether it is pod2man\, pod2html\, or whatever...). -- Larry W. Virden \mailto&#8203;:lvirden@&#8203;cas\.org \<URL​: http​://www.purl.org/NET/lvirden/> Unless explicitly stated to the contrary\, nothing in this posting should be construed as representing my employer's opinions. ->\<-

[p5pRT]

From @doughera88

On Thu\, 16 Mar 2000\, Richard Foley wrote​:

perldoc INSTALL /usr/bin/pod2man​: bad option in paragraph 52 of INSTALL​: ``-d'' should be [CB]\<-d> [etc.]

I don't have a specific proposal here\, but I think the INSTALL file is fine as is. This is a pod2man problem. Readers of INSTALL should not have to wade through non-plain pod markup just to decipher exactly what to type and what not to type to build and install perl. The INSTALL file ought to be readable\, as is\, by someone who has never touched perl or pod before.

Perhaps INSTALL needs some sort of

  =for pod2man quiet-already-I-know-what-I'm-doing

pragma or something near the top\, but please don't anyone go in and clutter up the current readable version with non-plain markup.

  Andy Dougherty doughera@​lafayette.edu   Dept. of Physics   Lafayette College\, Easton PA 18042

[p5pRT]

From [Unknown Contact. See original ticket]

I don't have a specific proposal here\, but I think the INSTALL file is fine as is. This is a pod2man problem. Readers of INSTALL should not have to wade through non-plain pod markup just to decipher exactly what to type and what not to type to build and install perl. The INSTALL file ought to be readable\, as is\, by someone who has never touched perl or pod before.

Then perhaps there should be an INSTALL.ascii and an INSTALL.pod\, no?

--tom

[p5pRT]

From @doughera88

On Thu\, 23 Mar 2000\, Tom Christiansen wrote​:

I don't have a specific proposal here\, but I think the INSTALL file is fine as is. This is a pod2man problem. Readers of INSTALL should not have to wade through non-plain pod markup just to decipher exactly what to type and what not to type to build and install perl. The INSTALL file ought to be readable\, as is\, by someone who has never touched perl or pod before.

Then perhaps there should be an INSTALL.ascii and an INSTALL.pod\, no?

No. Avoid needless duplication. One ought to be able to write plain old pod\, no? (Ok\, perhaps with some sort of pragma\, ...).

  Andy Dougherty doughera@​lafayette.edu

[p5pRT]

From [Unknown Contact. See original ticket]

No. Avoid needless duplication. One ought to be able to write plain old pod\, no? (Ok\, perhaps with some sort of pragma\, ...).

Would you say that having both *.pod and *.html is needless duplication. If you want to write plain text\, that that's fine.

The issue is that there's no way for a translator to know whether you mean the -d command-line switch or the -d filetest operator. We render those in two completely different fashions. If we find want that isn't marked\, we have no way of knowing which way to jump. So we tell the user about this.

I really don't see what else to do. I sympathize with your desire to write simple text. But I just can't see how to resolve something that cannot be guessed.

Don't worry. My next patch will be to warn about people who put mail addresses or URLs in C\<>\, which breaks them. :-)

--tom

[p5pRT]

From [Unknown Contact. See original ticket]

I really think that if the goal is to provide plain\, unmarked text\, that one should go ahead and do that.

--tom

[p5pRT]

From @doughera88

On Thu\, 23 Mar 2000\, Tom Christiansen wrote​:

The issue is that there's no way for a translator to know whether you mean the -d command-line switch or the -d filetest operator.

Or I might mean neither. There's absolutely no guarantee that info in the INSTALL file is talking about running or using perl.

I really don't see what else to do. I sympathize with your desire to write simple text. But I just can't see how to resolve something that cannot be guessed.

There ought to be a way to tell you not to bother to try to guess.   =for pod plain or   =for pod no warnings or some such pragma.

  Andy Dougherty doughera@​lafayette.edu

[p5pRT]

From [Unknown Contact. See original ticket]

There ought to be a way to tell you not to bother to try to guess. =for pod plain or =for pod no warnings or some such pragma.

=for ASCII

--tom

[p5pRT]

From [Unknown Contact. See original ticket]

perldoc INSTALL /usr/bin/pod2man​: bad option in paragraph 52 of INSTALL​: ``-d'' should be [CB]\<-d> [etc.]

Good news for you\, Andy! I went to hack your request to the --lax hack of Nathan's\, and found that this no longer occurs. Russ's current version produces this​:

  .PP   At any Configure prompt\, you can type &\-d and Configure will use the   defaults from then on.   .PP   After it runs\, Configure will perform variable substitution on all the   *.SH files and offer to run make depend.   .Sh "Altering config.sh variables for C compiler switches etc."   .IX Subsection "Altering config.sh variables for C compiler switches etc."   For most users\, all of the Configure defaults are fine. Configure   also has several convenient options which are all described below.   However\, if Configure doesn't have an option to do what you want\,   you can change Configure variables after the platform hints have been   run\, by using Configure's \-A switch. For example\, here's how to add   a couple of extra flags to C compiler invocations​:

Without the previous well-intentioned but quasiquerulent quips.

The docs do talk about how the --lint and/or --lax options are still unimplemented in the new version.

I have some concern that this will mean people won't be writing well-formed manpages anymore\, but that these will be nevertheless fed to the man system.

But that's for another day. For the nonce\, I think this should solve your needs.

--tom