[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Re: [PATCH 0/4] Bug#545548: Documentation updates

On Mon, Oct 05, 2009 at 12:36:44AM -0500, Manoj Srivastava wrote:
> Hi,
>         I have now updated the README docs with a slightly cleaner
>  work-flow. I would like to get a show of hands from the policy team
>  about this; and if people are OK with this approach (using org-mode,
>  with perhaps me committing to maintaining these documents in the
>  team), or abandoning this approach and going to plain old
>  HTML/docbook.

It is not realistic to expect you to maintain upgrading-checklist.org.
It is less a problem for Process.org and README.org since they change
less often.

>  Personally, I think that the .org files are easier to edit, even for
>  people who are unfamiliar with org-mode, and are mroe readable than
>  SGML based documents, and thus would have higher utility, but I'll
>  abide with what the rest of the team thinks.

Please find a SGML version of upgrading-checklist. This generate
much nicer upgrading-checklist.txt and has other advantage as well:
1) no generated files in VCS
2) no hidden build dependencies 
3) less risk of content being interpreted as formatting (e.g. /etc/ means
etc in italic for org-mode), which was a big issue with the
upgrading-checklist.org before I fixed .org file while writing
the .sgml one, but there might still be problems.
4) no need to learn yet another mark-up language
5) upgrading-checklist.org look really ugly under less.

Now, I agree that the SGML formatting is a bit verbose but if we decide to
use a markup language, we should pick one where the set of 'active' characters
is limited. org-mode has way to much of them. 

Bill. <ballombe@debian.org>

Imagine a large red swirl here. 

Attachment: signature.asc
Description: Digital signature

Reply to: