This updates the Python section of the porter's handbook to reflect the latest
conversion from bsd.python.mk to USES=python (rP364450)
Details
Details
- Reviewers
wblock - Group Reviewers
doceng Doc Committers - Commits
- rD45883: Add mva's updates to the Using Python section, with thanks to mat.
Diff Detail
Diff Detail
- Repository
- rD FreeBSD doc repository - subversion
- Lint
Lint Skipped - Unit
Tests Skipped
Event Timeline
| 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/ |
| en_US.ISO8859-1/books/porters-handbook/special/chapter.xml | ||
|---|---|---|
| 2683 ↗ | (On Diff #1019) | It does, really, you're just lagging behind :-) |
| 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: |
| 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 | ||
|---|---|---|
| 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 |
Comment Actions
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? |
Comment Actions
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. |
Comment Actions
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 :-)