You are not logged in.

#1 2013-06-14 12:56:33

graysky
Member
From: /run/user/1000
Registered: 2008-12-01
Posts: 8,524
Website

Punctuation in PKGBUILD files [SOLVED]

What is the official guidance regarding ending a pkgdesc in a period?  I find that the official packages are a mixed bag and I couldn't find a definitive answer in the official packing standards,

Last edited by graysky (2013-06-15 10:25:11)


CPU-optimized Linux-ck packages @ Repo-ck  • AUR packagesZsh and other configs

Offline

#2 2013-06-14 13:15:13

drcouzelis
Member
From: Connecticut, USA
Registered: 2009-11-09
Posts: 3,474
Website

Re: Punctuation in PKGBUILD files [SOLVED]

No period!

I think it was a few months ago that I noticed a bunch of changes in the git logs where periods were removed from package descriptions, but I have nothing to back that up...

Anyway, the description of the "pacman" package doesn't have a period. That's official enough for me.

Offline

#3 2013-06-14 14:29:52

progandy
Member
Registered: 2012-05-17
Posts: 2,151

Re: Punctuation in PKGBUILD files [SOLVED]

If your description contains multiple sentences, end it with a period. If it is no complete sentence, don't use it. If it is exactly one sentence, I don't know.

Offline

#4 2013-06-14 14:48:39

Trilby
Forum Moderator
From: Massachusetts, USA
Registered: 2011-11-29
Posts: 13,811
Website

Re: Punctuation in PKGBUILD files [SOLVED]

I agree with prograndy, from a strictly grammatical/stylistic[1] point of view.  I can't, however, imagine any decent one full-sentence package description.  A brief description should not have a verb: the description should not say "this is a XX tool with YY ability", rather it might say "XX tool with YY ability".  If one really must elaborate in multiple sentences, then they may have verbs, and thus be full sentences deserving of periods.  But if this is the case I think the maintainer should strive to be more concise.

[1] I'm basing this off of the prevailing adice on structuring list items such as bullet points.  Mignon Fogarty (aka Grammar Girl), among others, provide such advice.

Last edited by Trilby (2013-06-14 14:51:24)


InterrobangSlider
• How's my coding? See this page.
• How's my moderating? Feel free to email any concerns, complaints, or objections.

Online

#5 2013-06-14 15:09:12

graysky
Member
From: /run/user/1000
Registered: 2008-12-01
Posts: 8,524
Website

Re: Punctuation in PKGBUILD files [SOLVED]

Interesting opinions here.  Guess I should post this to the wiki discussion page in hopes of attracting someone on the dev team or a TU with authority to modify the rules.  A rough estimate not accounting for split packages:

EDIT: edited post based on Dave's code.

% sudo abs

### how many have periods in their pkgdesc lines

% for r in core extra community; do printf '%s: %s\n' "$r" "$(grep pkgdesc /var/abs/$r/*/PKGBUILD | grep -c \\..$)"; done
core: 4
extra: 98
community: 339

### how many total PKGBUILDs
% for i in core extra community; do; find /var/abs/$i -name 'PKGBUILD' | \
wc -l; done
176
1999
2571

So:

core 4/176 ~2 % end in period
extra 98/1999 ~5 % end in period
community 339/2571 ~13 % end in period

Last edited by graysky (2013-06-14 15:22:45)


CPU-optimized Linux-ck packages @ Repo-ck  • AUR packagesZsh and other configs

Offline

#6 2013-06-14 15:16:18

falconindy
Developer
From: New York, USA
Registered: 2009-10-22
Posts: 4,094
Website

Re: Punctuation in PKGBUILD files [SOLVED]

graysky wrote:

core 9/176 = 5 % end in period
extra 253/1999 = 13 % end in period
community 431/2571 = 17 % end in period

End in period? No... not really. 52 of those packages in [extra] contain "X.org". Many more of them are version numbers such as "Python 3.3", "GSM 06.10", or "glib 2.x".

I count 4 in core, 98 in extra, 339 in community.

for r in core extra community; do printf '%s: %s\n' "$r" "$(grep pkgdesc /var/abs/$r/*/PKGBUILD | grep -c \\..$)"; done

Offline

#7 2013-06-14 15:19:32

graysky
Member
From: /run/user/1000
Registered: 2008-12-01
Posts: 8,524
Website

Re: Punctuation in PKGBUILD files [SOLVED]

Your code is more elegant than mine, Dave.  I will edit my post with your numbers.  The point is that the official repos are inconsistent and there is no guidance in the wiki article referenced.


CPU-optimized Linux-ck packages @ Repo-ck  • AUR packagesZsh and other configs

Offline

#8 2013-06-14 15:20:34

falconindy
Developer
From: New York, USA
Registered: 2009-10-22
Posts: 4,094
Website

Re: Punctuation in PKGBUILD files [SOLVED]

Perhaps the conclusion you should draw is that you're the only one who cares about this minutia.

Offline

#9 2013-06-14 15:28:40

graysky
Member
From: /run/user/1000
Registered: 2008-12-01
Posts: 8,524
Website

Re: Punctuation in PKGBUILD files [SOLVED]

falconindy wrote:

Perhaps the conclusion you should draw is that you're the only one who cares about this minutia.

The packaging standards should provide clear guidance to users; I do not feel that this is in the category of minutia and apparently neither do the other three users who replied to the post (four counting you).

<offtopic>
Er... weren't you the one breaking my balls over, in part, my LACK of attention to details back in March on my TU application both in private emails and on AUR-general?!  Some consistency in your criticism would be appreciated.
</offtopic>

Last edited by graysky (2013-06-14 16:11:24)


CPU-optimized Linux-ck packages @ Repo-ck  • AUR packagesZsh and other configs

Offline

#10 2013-06-14 18:29:41

Trilby
Forum Moderator
From: Massachusetts, USA
Registered: 2011-11-29
Posts: 13,811
Website

Re: Punctuation in PKGBUILD files [SOLVED]

The fact that I responded doesn't mean I think it's important.  I'm more than happy to debate any useless topic.  Care to hear my views on US politics?

But, on point (no pun intended), would the ones that happen to end in a period also happen to contain full sentences?  This may be more relevant than the period itself.  I don't know where I saw it, but I recall a guideline for package descriptions much like what I echoed in my previous post: they should not be complete sentences, rather just a descriptive clause (noun phrase).

EDIT: I don't mean to disuade you - I do prefer instructions to be written out in explicit detail.  I recently was frustrated with a manual entry that claimed multiple entries could be provided for the setting of a variable and should be separated by a comma - but as there was no example I immediately wondered whether they should be separated by just a comma, or a comma and a space ... or either.  As I was having trouble getting that setting to work I was frustrated that I had to try every permutation to figure out if that inexact instruction was not part of the problem.

So I do support anyone else's OCD-ish pursuit of explicitly clear guidelines, even if it may be on minutia.  Perhaps it's my veteran side - I like to know exactly what the angle between my feet should be when I'm standing - and this should be written in a field manual somewhere.

Last edited by Trilby (2013-06-14 18:35:35)


InterrobangSlider
• How's my coding? See this page.
• How's my moderating? Feel free to email any concerns, complaints, or objections.

Online

#11 2013-06-14 18:58:48

drcouzelis
Member
From: Connecticut, USA
Registered: 2009-11-09
Posts: 3,474
Website

Re: Punctuation in PKGBUILD files [SOLVED]

Trilby wrote:

So I do support anyone else's OCD-ish pursuit of explicitly clear guidelines, even if it may be on minutia.

I think every good programmer is OCD-ish, since computers don't do so well with commands like "Put all of the big video files into the recycle bin unless it's been watched recently." tongue

Offline

#12 2013-06-14 19:10:21

Trilby
Forum Moderator
From: Massachusetts, USA
Registered: 2011-11-29
Posts: 13,811
Website

Re: Punctuation in PKGBUILD files [SOLVED]

I like watching recycle bins.  They're more entertaining than most of what has come out of Hollywood lately.


InterrobangSlider
• How's my coding? See this page.
• How's my moderating? Feel free to email any concerns, complaints, or objections.

Online

#13 2013-06-14 22:58:33

tomk
Forum Fellow
From: Ireland
Registered: 2004-07-21
Posts: 9,838

Re: Punctuation in PKGBUILD files [SOLVED]

I would be inclined to interpret the absence of official guidance regarding periods at the end of pkgdescs as an indication that there is in fact no official policy governing that particular topic, and I would therefore conclude that the inclusion or otherwise of the aforementioned punctuation mark in that particular position is entirely at the discretion of the package maintainer.

More briefly - why does it matter to you, graysky?

Offline

#14 2013-06-14 23:08:23

graysky
Member
From: /run/user/1000
Registered: 2008-12-01
Posts: 8,524
Website

Re: Punctuation in PKGBUILD files [SOLVED]

tomk wrote:

More briefly - why does it matter to you, graysky?

It's an unanswered question in a topic that is surrounded by guidance and rules.  Seems to me that for the sake of standardization, we do or do not.  Perhaps I am just OCD.


CPU-optimized Linux-ck packages @ Repo-ck  • AUR packagesZsh and other configs

Offline

#15 2013-06-14 23:30:47

tomk
Forum Fellow
From: Ireland
Registered: 2004-07-21
Posts: 9,838

Re: Punctuation in PKGBUILD files [SOLVED]

Sure, it's an unanswered question - but only because you asked it.

What benefit would accrue from standardizing it? Conversely, does not standardizing it cause any problems?

Remember, pkgdesc is just a string of text - the only standard that is required is that it should be readable by humans.

Offline

#16 2013-06-14 23:39:46

graysky
Member
From: /run/user/1000
Registered: 2008-12-01
Posts: 8,524
Website

Re: Punctuation in PKGBUILD files [SOLVED]

If the answer is, "there is no standard" then the wiki be edited to reflect that.  Offering no guidance invites uncertainty.  If I asked I would think that someone else wondered at some point too.


CPU-optimized Linux-ck packages @ Repo-ck  • AUR packagesZsh and other configs

Offline

#17 2013-06-14 23:46:56

cfr
Member
From: Cymru
Registered: 2011-11-27
Posts: 5,662

Re: Punctuation in PKGBUILD files [SOLVED]

When creating a package description for a package, do not include the package name in a self-referencing way. For example, "Nedit is a text editor for X11" could be simplified to "A text editor for X11". Also try to keep the descriptions to ~80 characters or less.

This might be interpreted as at least suggesting they should start with a capital letter and omit a final full stop. Personally, I think package descriptions look wrong when they are done this way as I think a capital at the start needs balancing at the end wink.

Last edited by cfr (2013-06-14 23:47:19)


How To Ask Questions The Smart Way | Help Vampires

Arch Linux | x86_64 | GPT | EFI boot | grub2 | systemd | LVM2 on LUKS
Lenovo x121e | Intel(R) Core(TM) i3-2367M CPU @ 1.40GHz GenuineIntel | Intel Centrino Wireless-N 1000 | US keyboard with Euro | 320G 7200 RPM Seagate HDD

Offline

#18 2013-06-14 23:50:53

tomk
Forum Fellow
From: Ireland
Registered: 2004-07-21
Posts: 9,838

Re: Punctuation in PKGBUILD files [SOLVED]

You still haven't answered any of my questions. And do you really think the packaging standards wiki page would be improved if we added

There is no standard governing the inclusion of periods at the end of the package description.

??

Offline

#19 2013-06-14 23:54:44

Trilby
Forum Moderator
From: Massachusetts, USA
Registered: 2011-11-29
Posts: 13,811
Website

Re: Punctuation in PKGBUILD files [SOLVED]

I'd prefer it said that there is not standard governing the exclusion of periods at the end of the package description.

But then this begs the question of whether there is a standard for when there is is no standard should the documentation should say there is no standard for the inclusion of the item in question, or no standard for the exclusion of the item in question.  Perhaps this question too should be answered in the wiki wink

Last edited by Trilby (2013-06-14 23:55:38)


InterrobangSlider
• How's my coding? See this page.
• How's my moderating? Feel free to email any concerns, complaints, or objections.

Online

#20 2013-06-15 00:04:17

graysky
Member
From: /run/user/1000
Registered: 2008-12-01
Posts: 8,524
Website

Re: Punctuation in PKGBUILD files [SOLVED]

@tomk - I think I did answer your questions. 

graysky wrote:

If the answer is, "there is no standard" then the wiki be edited to reflect that.  Offering no guidance invites uncertainty.  If I asked I would think that someone else wondered at some point too.

Including a sentence as you or Trilby proposed would remove the ambiguity surrounding the question.


CPU-optimized Linux-ck packages @ Repo-ck  • AUR packagesZsh and other configs

Offline

#21 2013-06-15 01:37:44

tomk
Forum Fellow
From: Ireland
Registered: 2004-07-21
Posts: 9,838

Re: Punctuation in PKGBUILD files [SOLVED]

graysky wrote:

@tomk - I think I did answer your questions.

Rapidly losing interest here, but let's recap:
ME: Why does it matter?
YOU: It's an unanswered question

ME: What benefit would accrue from standardizing it?
YOU: (no answer)

ME: Does not standardizing it cause any problems?
YOU: Offering no guidance invites uncertainty

You're happy with those "answers"? The only thing I can respond to there is that alleged uncertainty, and as I already pointed out, pkgdesc is just human-readable text - the presence or absence of a period at the end of the description makes absolutely no difference, so whatever uncertainty there might be is irrelevant in this context.

Last edited by tomk (2013-06-15 01:38:32)

Offline

#22 2013-06-15 10:24:18

graysky
Member
From: /run/user/1000
Registered: 2008-12-01
Posts: 8,524
Website

Re: Punctuation in PKGBUILD files [SOLVED]

tomk wrote:

Rapidly losing interest here...

Yeah, me too.

tomk wrote:

pkgdesc is just human-readable text - the presence or absence of a period at the end of the description makes absolutely no difference, so whatever uncertainty there might be is irrelevant in this context.

So put that or something like it on the wiki page and let's call it good.


CPU-optimized Linux-ck packages @ Repo-ck  • AUR packagesZsh and other configs

Offline

Board footer

Powered by FluxBB