Michael Schroeder
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.
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
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 ***************************************** 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@opensuse.org For additional commands, e-mail: opensuse-packaging+help@opensuse.org