#104970: Update and rename perl.xml to perl.md #105175

StefanSchroeder · 2020-11-27T20:19:08Z

Motivation for this change

Addresses #104970, conversion of Docbook language-support for Perl to CommonMark.

Things done

StefanSchroeder · 2020-11-27T20:20:41Z

I have deliberately not updated the index.xml, because I expect that the PR will be rejected. But I am interested in the review comments to improve it before actually merging it.

ryantm · 2020-11-27T20:47:40Z

I think you should update the index it makes it easier to test it.

ryantm · 2020-11-27T22:40:36Z

perl.md needs to be called perl.section.md

ryantm · 2020-11-27T22:59:36Z

doc/languages-frameworks/perl.md

+```
+to take the Perl installation from the `PATH` environment variable, or invoke Perl directly with:
+
+```


Suggested change

```

```ShellSession

Please use ShellSession for these ones.

ryantm · 2020-11-27T23:00:58Z

doc/languages-frameworks/perl.md

@@ -0,0 +1,181 @@
+# Perl


Suggested change

# Perl

# Perl {#sec-language-perl}

We don't want to break anchor links.

ryantm · 2020-11-27T23:02:10Z

doc/languages-frameworks/perl.md

+
+## Packaging Perl programs
+
+   Nixpkgs provides a function *buildPerlPackage*, a generic package builder function for any Perl package that has a standard *Makefile.PL*. It’s implemented in 


Suggested change

Nixpkgs provides a function *buildPerlPackage*, a generic package builder function for any Perl package that has a standard *Makefile.PL*. It’s implemented in

Nixpkgs provides a function `buildPerlPackage`, a generic package builder function for any Perl package that has a standard `Makefile.PL`. It’s implemented in

I think it's more idiomatic in Markdown to use literals instead of emphasis for this kind of thing.

Also the indentation looks weird.

ryantm · 2020-11-27T23:02:51Z

doc/languages-frameworks/perl.md

+   Perl packages from CPAN are defined in
+   [pkgs/top-level/perl-packages.nix](https://github.com/NixOS/nixpkgs/blob/master/pkgs/top-level/perl-packages.nix) rather than `pkgs/all-packages.nix`. Most Perl packages are so straight-forward to build that they are defined here directly, rather than having a separate function for each package called from `perl-packages.nix`. However, more complicated packages should be put in a separate file, typically in `pkgs/development/perl-modules`. Here is an example of the former:
+
+```


Suggested change

```

```nix

Bunch of places need this change.

StefanSchroeder · 2020-11-28T13:46:28Z

I have updated the files (index.xml & perl.section.md) but I don't know what to do next.
Do I need to file another PR?

ryantm · 2020-11-28T14:13:29Z

Do I need to file another PR?

No, your changes got reflected in this one. I'll take a look in a bit, thanks!

doc/languages-frameworks/perl.section.md

StefanSchroeder · 2020-11-28T18:14:15Z

I hadn't seen the "Commit suggestion" button before. That's so much quicker!

jtojnar · 2020-12-03T06:24:55Z

doc/languages-frameworks/perl.section.md

+}
+```
+
+Dependencies on other Perl packages can be specified in the ´buildInputs´ and ´propagatedBuildInputs´ attributes. 


Somehow backticks got turned to forward ticks.

That's weird, no idea how that happened. Fixed multiple occurrences.

jtojnar · 2020-12-03T06:27:33Z

doc/languages-frameworks/perl.section.md

+So what does ´buildPerlPackage´ do? It does the following:
+
+1. In the configure phase, it calls `perl Makefile.PL` to generate a Makefile. You can set the variable `makeMakerFlags` to pass flags to `Makefile.PL`
+2. It adds the contents of the <envar>PERL5LIB</envar> environment variable to `#! .../bin/perl` line of Perl scripts as `-I<replaceable>dir</replaceable>` flags. This ensures that a script can find its dependencies. (This can cause this shebang line to become too long for Darwin to handle; see the note below.)


Replaceables have not been replaced.

Fixed and . Multiple instances.

jtojnar · 2020-12-03T06:34:26Z

doc/languages-frameworks/perl.section.md

+This will remove the `-I` flags from the shebang line, rewrite them in the `use lib` form, and put them on the next line instead. 
+This function can be given any number of Perl scripts as arguments; it will modify them in-place.
+
+## Generation from CPAN {#ssec-generation-from-CPAN}


This section and the one below previously belonged under “Packaging Perl programs”. Is this change intentional?

No, it was not intentional. When looking at the XML source it's difficult to keep track of this kind of detail. It's fixed by increasing the section level from '##' to '###'. Hope that's supported.

StefanSchroeder · 2020-12-03T20:51:26Z

I'll fix it coming weekend.

jtojnar · 2020-12-04T21:55:45Z

doc/languages-frameworks/perl.section.md

+This happens when the script expects Perl to be installed at `/usr/bin/perl`, which is not the case when using Perl from nixpkgs. 
+You can fix the script by changing the first line to:
+
+```ShellSession


This is a perl snippet.

jtojnar · 2020-12-04T21:56:02Z

doc/languages-frameworks/perl.section.md

+
+If you are always using the script in places where `nix-shell` is available, you can embed the `nix-shell` invocation in the shebang like this:
+
+```ShellSession


jtojnar · 2020-12-04T21:58:42Z

doc/languages-frameworks/perl.section.md

+
+## Packaging Perl programs {#ssec-perl-packaging}
+
+Nixpkgs provides a function `buildPerlPackage`, a generic package builder function for any Perl package that has a standard `Makefile.PL`. It’s implemented in 


Why are the lines split frequently? Try using the formatter from #105243

I wasn't aware that there is a formatter. I will try it out next.

@jtolnar I am unable to squash my commits. Trying to follow the instructions here https://medium.com/@mittalyashu/how-to-squash-commits-in-a-github-pull-request-97b36576eacb leads to a tremendous amount of merge conflicts by commits that I didn't make... Please advise.
"Auto-merging pkgs/top-level/all-packages.nix
CONFLICT (content): Merge conflict in pkgs/top-level/all-packages.nix
error: could not apply a64d7d8... Revert "Revert "texinfo: revert to version 6.5 on Darwin""
"

For squashing, I would suggest rebasing onto the parent commit of your first commit instead of master. That way you will have less commits to worry about.

git rebase -i c7a82285f6c63816b66e78fa1b66fb2bfbe67f8f^

But note that you will need to rebase onto master anyway, to resolve the conflict in index.xml.

jtojnar · 2020-12-04T22:03:36Z

Also, could you please squash the changes?

StefanSchroeder · 2020-12-06T16:12:49Z

@jtojnar: This is a shoutout to @jtojnar for kindly and patiently guiding me through the commit process of my first contribution. (I don't know what I am doing here. Luckily on the internet no one knows you're a dog.)

jtojnar · 2020-12-07T07:47:34Z

Thanks.

I have rebased it since another merge conflict sneaked in and will merge this after the CI finishes,

ofborg bot added 8.has: documentation 10.rebuild-darwin: 0 10.rebuild-linux: 0 labels Nov 27, 2020

ryantm linked an issue Nov 27, 2020 that may be closed by this pull request

Convert Perl from Docbook to CommonMark #104970

Closed

ryantm requested changes Nov 27, 2020

View reviewed changes

jtojnar reviewed Nov 28, 2020

View reviewed changes

doc/languages-frameworks/perl.section.md Outdated Show resolved Hide resolved

jtojnar reviewed Nov 28, 2020

View reviewed changes

doc/languages-frameworks/perl.section.md Outdated Show resolved Hide resolved

jtojnar reviewed Nov 28, 2020

View reviewed changes

doc/languages-frameworks/perl.section.md Outdated Show resolved Hide resolved

jtojnar reviewed Nov 28, 2020

View reviewed changes

doc/languages-frameworks/perl.section.md Outdated Show resolved Hide resolved

jtojnar reviewed Dec 3, 2020

View reviewed changes

jtojnar reviewed Dec 4, 2020

View reviewed changes

ofborg bot added the 2.status: merge conflict label Dec 6, 2020

doc: Port Perl to Markdown

9d70829

ofborg bot removed the 2.status: merge conflict label Dec 7, 2020

jtojnar merged commit 6571462 into NixOS:master Dec 7, 2020

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

#104970: Update and rename perl.xml to perl.md #105175

#104970: Update and rename perl.xml to perl.md #105175

StefanSchroeder commented Nov 27, 2020

StefanSchroeder commented Nov 27, 2020

ryantm commented Nov 27, 2020

ryantm commented Nov 27, 2020

ryantm Nov 27, 2020

ryantm Nov 27, 2020

ryantm Nov 27, 2020

jtojnar Nov 28, 2020

ryantm Nov 27, 2020

StefanSchroeder commented Nov 28, 2020

ryantm commented Nov 28, 2020

StefanSchroeder commented Nov 28, 2020

jtojnar Dec 3, 2020

StefanSchroeder Dec 4, 2020 •

edited

jtojnar Dec 3, 2020

StefanSchroeder Dec 4, 2020

jtojnar Dec 3, 2020

StefanSchroeder Dec 4, 2020

StefanSchroeder commented Dec 3, 2020

jtojnar Dec 4, 2020

jtojnar Dec 4, 2020

jtojnar Dec 4, 2020

StefanSchroeder Dec 5, 2020

StefanSchroeder Dec 5, 2020

jtojnar Dec 5, 2020

jtojnar commented Dec 4, 2020

StefanSchroeder commented Dec 6, 2020 •

edited

jtojnar commented Dec 7, 2020


		## Packaging Perl programs

		Nixpkgs provides a function buildPerlPackage, a generic package builder function for any Perl package that has a standard Makefile.PL. It’s implemented in

	Nixpkgs provides a function buildPerlPackage, a generic package builder function for any Perl package that has a standard Makefile.PL. It’s implemented in
	Nixpkgs provides a function `buildPerlPackage`, a generic package builder function for any Perl package that has a standard `Makefile.PL`. It’s implemented in


		If you are always using the script in places where `nix-shell` is available, you can embed the `nix-shell` invocation in the shebang like this:

		```ShellSession


		## Packaging Perl programs {#ssec-perl-packaging}

		Nixpkgs provides a function `buildPerlPackage`, a generic package builder function for any Perl package that has a standard `Makefile.PL`. It’s implemented in

#104970: Update and rename perl.xml to perl.md #105175

#104970: Update and rename perl.xml to perl.md #105175

Conversation

StefanSchroeder commented Nov 27, 2020

Motivation for this change

Things done

StefanSchroeder commented Nov 27, 2020

ryantm commented Nov 27, 2020

ryantm commented Nov 27, 2020

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

StefanSchroeder commented Nov 28, 2020

ryantm commented Nov 28, 2020

StefanSchroeder commented Nov 28, 2020

Choose a reason for hiding this comment

StefanSchroeder Dec 4, 2020 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

StefanSchroeder commented Dec 3, 2020

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jtojnar commented Dec 4, 2020

StefanSchroeder commented Dec 6, 2020 • edited

jtojnar commented Dec 7, 2020

StefanSchroeder Dec 4, 2020 •

edited

StefanSchroeder commented Dec 6, 2020 •

edited