Re: Proposed new initiative: include HTML documentation
Hi!
A while ago I created a patch to do exactly this.
1397862133-17762-1-git-send-email-avtobiff@gmail.com
With some slight modifications it should be usable.
I didn't get any final review and grew busy with other things.
--
Per
On Thu, Aug 28, 2014 at 9:29 PM, Caitlin Matos <caitlin.matos@zoho.com> wrote:
> Hi all,
>
> I would like to propose some goals and initiatives for maintaining proper
> documentation and also supporting newcomers to Debian looking for ways to
> contribute.
>
> One thing I've noticed about Ruby packages is that documentation files are
> often installed as plain-text when they should be converted to HTML. This
> especially includes any documentation with the suffix *.md or *.rdoc. While
> Markdown and RDoc markup syntax is generally readable in its raw format,
> these should be converted to HTML for numerous reasons. For one, many of the
> markup language's features (e.g., pretty formatting and syntax highlighting)
> are lost. For another, Debian Policy is to use HTML.[1]
>
> Also, even if a package does not include any *.rdoc files, many include RDoc
> strings. Policy states that additional documentation can be installed "at
> the discretion of the package maintainer". Personally, I believe in having
> as much documentation as possible available from Debian and on the user's
> system. Therefore, I think that these packages should be running their files
> through RDoc and including this documentation in a separate *-doc package.
>
> Adding and generating this documentation is really very easy (you're not
> writing the documentation, just installing it). Therefore, I think this
> could be a great way for newcomers to contribute to Debian. I would create a
> tutorial on the wiki on how to edit debian/rules to build the documentation.
> I would also go through the packages and label them with "gift",[2] so they
> would appear via the how-can-i-help application.[3]
>
> In total, what I'd like to do is:
> * Comb through the packages and figure out which ones have documentation
> available but not being installed via HTML
> * File a bug against these packages, using the usertag 'ruby-doc' (or
> similar)
> * Label appropriate packages/bugs with the usertag 'gift'
> * Create a tutorial on how to include documentation
>
> The one downside I envision is an influx of RFS and Alioth access requests,
> which is good or bad, depending on your perspective. As I am not a DD, I
> cannot help with this part. Therefore, I don't want to undertake this
> project without some feedback from DDs (and anyone else). Note that I would
> encourage submitting patches to BTS instead of requesting write-access to
> the repo, which might ease the burden a bit. I or someone else would then
> upload the patches to git and submit RFS e-mails in bulk to lessen the
> mailing list traffic.
>
> It would be nice to have this as a release goal for jessie, but it's
> probably too late.
>
> I would like some feedback as to whether this is a worthwhile initiative
> and/or other ideas. Please discuss over the mailing list, or during the Ruby
> BoF on Friday.
>
> Thanks,
> Caitlin
>
> [1] https://www.debian.org/doc/debian-policy/ch-docs.html#s12.4
> [2] https://wiki.debian.org/qa.debian.org/GiftTag
> [3] https://wiki.debian.org/how-can-i-help
>
>
> --
> To UNSUBSCRIBE, email to debian-ruby-REQUEST@lists.debian.org
> with a subject of "unsubscribe". Trouble? Contact
> listmaster@lists.debian.org
> Archive: [🔎] 53FF832C.8010101@zoho.com">https://lists.debian.org/[🔎] 53FF832C.8010101@zoho.com
>
Reply to: