setup.hint documentation issues

[Jon Turney]

On 09/02/2016 17:10, Corinna Vinschen wrote:
> On Feb  9 13:18, Jon Turney wrote:
>> * 'sdesc' text is mangled in setup.ini (but not the HTML package list)
>>
>> In particular, it is forced to start with a capital letter (which is
>> incorrect when the sdesc starts with a command name which is properly
>> lower-case, e.g. "dash shell", etc.), and any text up to and including the
>> first colon is removed, presumably in an effort to prevent people writing
>> the package name again, (which mangles perl and ruby module names in the
>> description, e.g. "Ruby Net::HTTP persistent connection support", ""Perl
>> Math::Int64 distribution", etc.)
>>
>> I'd suggest this mangling is removed, and sdesc starting "packagename:" is
>> explicitly reported.
>
> Sounds good, but where is this mangling performed?  Upset?

Yes, upset currently does this mangling.

>> * Handling of double-quoted text seems over-complicated
>>
>> A multi-line double-quoted value is terminated only by a double-quote at the
>> end of the line, and embedded double-quotes are silently transformed to
>> single-quotes (e.g proj had a sdesc of ""The PROJ Cartographic Projections
>> Software (utilities)", where the erroneous nested double-quote was being
>> transformed to a single-quote)
>>
>> There is no escaping of embedded double-quotes, and no way to represent one.
>>
>> Additionally, spaces after the leading quote are magically removed.
>>
>> Additionally, genini requires that sdesc and ldesc are double-quoted, but
>> upset does not.
>>
>> I'd suggest that double-quoting of those keys is made mandatory, and
>> embedded double-quotes are forbidden, as this permits simpler processing of
>> this text, lexing character by character.
>
> What about existing packages?

I've fixed the existing uses on sourceware (which were proj and I think 
one other package I unfortunately didn't take note of)

>> * It's not very clear what 'skip' represents
>>
>> The description "The skip line indicates that that package should not appear
>> in setup. It is intended for directories that exist in the hierarchy that
>> should not be considered." is a bit vague to me.
>>
>> It's not totally clear if it's intended for indicating directories which
>> should be empty, source-only packages, or something else.
>>
>> upset knows enough to omit packages which have no install tarfiles (i.e. are
>> source-only) from from setup.ini, irrespective of 'skip'.
>>
>> However, the presence of 'skip' also causes the package to be omitted from
>> the HTML package list.
>>
>> I think cygport's behaviour has changed over time, but currently will mark
>> source-packages as 'skip', however there are several packages that are
>> source-only (e.g. attica), that are missing 'skip'.
>
> IMHO we don't need "skip".  A source-only package should be
> automatically skipped anyway.  What other reason do we need to ignore
> a package?

Yes, this is why I ask the question.

I don't see what 'skip' adds above automatically noticing that there are 
no install tar files, only source tar files.