[csw-maintainers] ITP: opencsw-policy

[Peter FELECAN]

"Maciej (Matchek) Blizinski" <maciej at opencsw.org> writes:

> No dia 29 de Dezembro de 2010 18:44, Peter FELECAN
> <pfelecan at opencsw.org> escreveu:
>> "Maciej (Matchek) Blizinski" <maciej at opencsw.org> writes:
>>
>>> The policy will be written as a collection of text files in a
>>> lightweight markup.  I suggest asciidoc.  During build phase, asciidoc
>>> files will be transformed into HTML files (also potentially PDF and
>>> troff).  The package will install all files (in all formats) into
>>> /opt/csw/share/doc/opencsw_policy.
>>
>> What's "asciidoc"? The figures are done doing "asciiart"? Seriously, I
>> know TeX/LaTeX, texinfo or docbook (Debian use this), all of them
>> convertible to all kind of output (PS, PDF, HTML, &c)
>
> Asciidoc is usually the source from which TeX//LaTeX and docbook files
> are generated, as a middle step to other formats.  As much as I like
> LaTeX, I would like us to avoid typing in all the backslashes and
> braces by hand.  Docbook is even worse.  If you take a second to look
> at asciidoc, you'll see the idea behind it: it's a minimal markup
> language, the document you write is basically a plain text file with
> almost no markup.
>
> If for some reason people don't like this particular one, there's also
> reStructuredText, textile, markdown, and a couple others. Suggestions
> welcome.

IMO, LaTeX is less about backslashes than document format and good
typography. Other than using macros you don't need a lot of special
characters...

For reference, the home of the project is
http://www.methods.co.nz/asciidoc/

It uses also special characters, a lot of ~, [], {} which are not easier
than \ on a US keyboard --- which is a must for a programmer anyway.

In asciidoc, the document structure is written:

    [[X1]]
    Sub-section with Anchor
    ~~~~~~~~~~~~~~~~~~~~~~~
    Sub-section at level 2.
    
    Chapter Sub-section
    ^^^^^^^^^^^^^^^^^^^
    Sub-section at level 3.
    
    Chapter Sub-section
    +++++++++++++++++++
    Sub-section at level 4.
    
    This is the maximum sub-section depth supported by the distributed
    AsciiDoc configuration.
    
    footnote:[A second example footnote.]

In LaTeX:

    \chapter{Sub-section with Anchor}
    \ref{chap:anchor}
    
    Sub-section at level 2.
    
    \subsection{Chapter Sub-section}
    
    Sub-section at level 3.
    
    \subsubsection{Chapter Sub-section}
    
    Sub-section at level 4.
    
    This is not the maximum sub-section depth supported by LaTeX
    configuration.

    \footnote{A second example footnote.}

Well, for this small example, asciidoc requires 408 characters when
Latex requires 378... I know that this is naïve and anyway I don't want
to start a typographic language war. What about a pool about the
typographic language that is most known by our community?

>>> Changes to the policy will be posted to the maintainers (or the devel)
>>> list for discussion.  The initial submissions will be ports of
>>> existing documentation on the wiki and in Wordpress.  Any subsequent
>>> changes will be also posted to the mailing list before submission.
>>
>> We need a policy mailing list which should be private.
>
> What would be the purpose of that mailing list and why should it be
> private?  The source updates will be public.

Privacy: policies discussions can be tempestuous, especially in the
         initial phase; no need to wash our laundry in public...

Isolation: polices discussion are not drowned in the general noise which
           make them clearer; using many lists can be confusing
           reference wise.

>> and use a voting system.
>> BTW, can we have an official voting system/procedure?
>
> The online voting system we used had a couple of shortcomings (did not
> understand time zones, for instance).  We can still use it though.  We
> could start another thread to find and test online voting systems.

Do you wish to open the specific thread?
-- 
Peter