Page MenuHomeFreeBSD

Update to the Python section for USES=python
ClosedPublic

Authored by mva on Aug 9 2014, 7:52 PM.
Tags
None
Referenced Files
Unknown Object (File)
Mon, Feb 24, 3:22 PM
Unknown Object (File)
Tue, Feb 18, 12:34 PM
Unknown Object (File)
Jan 29 2025, 11:40 AM
Unknown Object (File)
Jan 23 2025, 2:34 AM
Unknown Object (File)
Dec 30 2024, 5:11 AM
Unknown Object (File)
Dec 13 2024, 2:25 PM
Unknown Object (File)
Dec 10 2024, 10:25 PM
Unknown Object (File)
Nov 30 2024, 12:45 AM
Subscribers

Details

Summary

This updates the Python section of the porter's handbook to reflect the latest
conversion from bsd.python.mk to USES=python (rP364450)

Diff Detail

Repository
rD FreeBSD doc repository - subversion
Lint
Lint Skipped
Unit
Tests Skipped

Event Timeline

mva retitled this revision from to Update to the Python section for USES=python.
mva updated this object.
mva edited the test plan for this revision. (Show Details)
  • Be more clear about how to use min/max versions with USES=python
wblock added inline comments.
en_US.ISO8859-1/books/porters-handbook/special/chapter.xml
2609 ↗(On Diff #1019)

s/Minimal/The minimal/

2612 ↗(On Diff #1019)

The comma is unnecessary here:

specified by separating two version numbers with a

2613 ↗(On Diff #1019)

That e.g. is not helping and can be removed:

dash: <literal>USES=python:3.2-3.3</literal></entry>

2618 ↗(On Diff #1019)

Harvard/Oxford comma:

s/compiling/compiling,/

2683 ↗(On Diff #1019)

That file does not exist on my system, r364482.

en_US.ISO8859-1/books/porters-handbook/uses/chapter.xml
795 ↗(On Diff #1019)

There should be <replaceable> tags around the values that are to be replaced by the user. These are not an actual "X" or "Y":

<literal><replaceable>X</replaceable>.<replaceable>Y</replaceable></literal>

The next two lines have these also.

800 ↗(On Diff #1019)

No comma.

801 ↗(On Diff #1019)

s/as/as a/

mat added inline comments.
en_US.ISO8859-1/books/porters-handbook/special/chapter.xml
2683 ↗(On Diff #1019)

It does, really, you're just lagging behind :-)
I don't like sending people to read files, the variables should be available in the handbook, either in this section, or in the USES=python section.

en_US.ISO8859-1/books/porters-handbook/special/chapter.xml
2683 ↗(On Diff #1019)

Okay, it's there now.

Agreed that referring people to files is ugly. An alternate method is to link to that file in svnweb:
<link xlink:href="http://svnweb.freebsd.org/ports/head/Mk/Uses/python.mk?view=co"></link>

en_US.ISO8859-1/books/porters-handbook/special/chapter.xml
2683 ↗(On Diff #1019)

I have been thinking about this yesterday evening, would be best to add this as is, it is not bad and I would rather have this in sooner than later. I will go over it when it is in and document all variables here.

en_US.ISO8859-1/books/porters-handbook/special/chapter.xml
2617 ↗(On Diff #1019)

Note that we have D581 cooking, which will replace PYTHON_FEATURES with USE_PYTHON to avoid inconsistencies. I'll go over the requested changes later today.

en_US.ISO8859-1/books/porters-handbook/special/chapter.xml
2683 ↗(On Diff #1019)

I'm not sure about a plain documentation of the variables, since this certainly won't help people to identify, when those are needed.

Rather than just jotting down the variables, always lagging behind changes in python.mk, I'd like to create a set of context-based examples for the most important variables, so people actually know how and when to use them.

en_US.ISO8859-1/books/porters-handbook/special/chapter.xml
2683 ↗(On Diff #1019)

Well, lagging behind is because nobody ever really maintained the PHB, I'm doing it now, so it doesn't lag too much behind. It is important that things are documented outside the sources, not everyone likes to have to read through comments and code to figure out what things really do, people want one source of information, possibly nicely formatted, that's what the PHB is :-)

en_US.ISO8859-1/books/porters-handbook/special/chapter.xml
2683 ↗(On Diff #1019)

Understood :-). How about the following then:

We'll (Python) provide you the list of python-related knobs along with examples, so users know, how and when to use those. This should be better than just copy-pasting the knobs from the .mk file

Yes, I just got distracted, sorry.

  • Fix typos
  • Add small example

I do not have the time to create a more elaborate documentation at the moment and we should not keep the handbook outdated until I'm done with anything related to that.
Instead, I would want to see the current changes and updates to be pushed into the docs.

en_US.ISO8859-1/books/porters-handbook/special/chapter.xml
2795 ↗(On Diff #1945)

The second sentence can be more clear:

A unique prefix will be used for directories like <varname>EXAMPLESDIR</varname> and <varname>DOCSDIR</varname>. A suffix will be appended to the names of binaries and scripts.

(What suffix? Why? Is it ".py"?)

2860 ↗(On Diff #1945)

s/simple/Simple/

en_US.ISO8859-1/books/porters-handbook/uses/chapter.xml
965 ↗(On Diff #1945)

The comma is needed on this line, it should be removed from the next line.

en_US.ISO8859-1/books/porters-handbook/uses/chapter.xml
965 ↗(On Diff #1945)

There is only one comma in this paragraph. What do you mean?

  • Improve "concurrent" description
  • Fix comma (hopefully)
  • Try to get another comma right

A few more comments. If you are pressed for time, make sure the current version builds, commit it, and I'll edit it.

en_US.ISO8859-1/books/porters-handbook/special/chapter.xml
2795 ↗(On Diff #1947)

s/an unique/a unique/

The entries tagged as <literal> are actually make variables, and should use <varname> tags.

en_US.ISO8859-1/books/porters-handbook/uses/chapter.xml
965 ↗(On Diff #1945)

The previous change removed a comma from the wrong line, and left the one that should have been removed. It is correct now.

en_US.ISO8859-1/books/porters-handbook/special/chapter.xml
2744 ↗(On Diff #1948)

You should put the space back, the rule is bla.<space><space>Bla

2859 ↗(On Diff #1948)

Could be nice to have the current complete list available in there, either here or in the USES chapter. But it can wait for later.

en_US.ISO8859-1/books/porters-handbook/uses/chapter.xml
968 ↗(On Diff #1948)

You could add something like See <xref linkend="using-python"/> for more information.

  • Readded double space
  • Added "see also" link
wblock added a reviewer: wblock.

Let's just commit this. Please build-test first, though.

This revision is now accepted and ready to land.Oct 21 2014, 10:04 PM
In D573#30, @wblock wrote:

Let's just commit this. Please build-test first, though.

I do not have a doc commit bit, so who can pick this up?

In D573#34, @mva wrote:

I do not have a doc commit bit, so who can pick this up?

You don't need a doc commit bit, you can commit in any freebsd repository with only one bit. (You did commit in the doc and src repositories when you became a committer.)

Just add Approved by: wblock :-)

wblock updated this revision to Diff 2143.

Closed by commit rD45883 (authored by @wblock).