Mailinglist Archive: opensuse-packaging (158 mails)

< Previous Next >
Re: [opensuse-packaging] Package Descriptions
  • From: Karl Eichwalder <ke@xxxxxxx>
  • Date: Fri, 10 Sep 2010 12:18:05 +0200
  • Message-id: <shaanprjfm.fsf@xxxxxxxxxxxxxxx>
Michael Schroeder <mls@xxxxxxx> writes:

On Fri, Sep 10, 2010 at 10:54:28AM +0200, Karl Eichwalder wrote:
By now, package descriptions are rather bewildered, and there is doubt
about there formatting. Time ago, they were maintained in a separate
database (PDB) and exported for yast and .spec files as needed.

Now, we parse the .spec files to create something suitable for yast.
Because many a lot \n\n (AKA empty lines) are gone, paragraphs and list
items (= lines starting with "* ") run into one paragraph.

How do we want to proceed with the package description formatting?

Patch yast so that it understands list items.

It already does or did, if it see html-like tags. But first we must
agree how we want to "tag" the description snippets in the spec files.
These are the old formatting rules; do they still apply?



Formatting Rules for Package Descriptions
*****************************************

From 8.2 on, we have the possibility to pass html formatted package
descriptions to YaST. That results in a much better look and feel
because YaST displays html then and not longer plain text. For that,
code was implemented that converts the existing plain text silently to
html and plain text. Both the html and plain text need to go to
autobuild in order to be included in the yast database (html format) and
the rpm files (ascii format).

Basic formatting
================

* empty lines will be <p> tags. In a list environment, empty lines
end the list. In ascii mode they remain empty lines. linebreaks
result in a single space, that means that a line break has no
special effect.

* a not numbered list environment starts with a line that starts
with an asterix or a minus sign followed by at least one
whitespace.

* a numbered list environment starts with a line that starts with an
#

* at least two minus-signs on a line followed by whitespace form a
horizontal line

* headers are done by inserting the header text into equal
signs. The number of equal signs form the level of the heading::
==Second level heading== creates a header second level.

Note that headers should not be used in package descriptions at the moment.


Text Face
=========
Text can be formatted to have different face. This should be used in a
consistent manner over all package descriptions. TODO: Can somebody
provide a guideline?

Note: Ascii does not honor the tags.

* Bold text: Embed the text in three single '''quotes'''

* Italic: Embed the text in two single quotes.

* typewriter font (e.g. for paths etc.): Embed the text in two
{{curly brackets}}

* Preformatted typewriter text: Embed text in three {{{curly
brackets}}}. This text should be preformatted to 72 characters per
line.

Package Links
=============
Text can contain links to other packages we provide on the
distribution. YaST offers the links and on activation, YaST jumps to the
package.

There are two possibilities to specify links:

* [pkg://packname] inserts a link to a package. The package name is
displayed in Yast. The package needs to exist in the release.

* [pkg://package Description] inserts the link to package but shows
the description in the text.

The PDB checks if the package pointed to does exist in the SuSE release.

Package links in Descriptions can help to make the package selection
more comfortable for users. This example:

... Kooka supports OCR by calling the commandline tool gocr

contains a link to gocr instead of only mentioning it. The user can
select Kooka in YaST and afterwards jump to gocr and check if gocr
should also be selected for installation.

--
Karl Eichwalder
R&D / Documentation

SUSE LINUX Products GmbH, GF: Markus Rex, HRB 16746 (AG Nuernberg)
--
To unsubscribe, e-mail: opensuse-packaging+unsubscribe@xxxxxxxxxxxx
For additional commands, e-mail: opensuse-packaging+help@xxxxxxxxxxxx

< Previous Next >
Follow Ups