PackagingDrafts/HtmlDocs

From FedoraProject

< PackagingDrafts(Difference between revisions)
Jump to: navigation, search
(clarify the Jan Pazdziora's idea)
m (reformat)
 
(3 intermediate revisions by one user not shown)
Line 7: Line 7:
 
== Proposal ==
 
== Proposal ==
  
While '''info''' documents should remain available proposing to also generate single-page '''html''' format.  As '''info''' is normally stored compressed ('''.info.gz''', 411KB) it is much smaller than '''.html''' (2280KB).
+
While '''info''' documents should remain available proposing to also generate single-page '''html''' format and the '''pdf''' format.
  
Therefore proposing to move both the '''info''' and '''html''' documentation into separate '''-doc''' subpackages.  Man pages are generally available still in the main packages for the basic information.
+
As '''info''' is normally stored compressed ('''.info.gz''', 411KB) it is much smaller than '''.html''' (2280KB).  Therefore proposing to move both all the '''info''', '''html''' and '''pdf''' documentation into separate '''-doc''' subpackages.  Man pages are generally available still in the main packages for the basic information.
  
 
== Example ==
 
== Example ==
  
Package [https://koji.fedoraproject.org/koji/buildinfo?buildID=228866 gdb-7.2.50.20110213-22.fc15] is now using the proposed format.
+
Package [https://koji.fedoraproject.org/koji/buildinfo?buildID=228879 gdb-7.2.50.20110213-23.fc15] is now using the proposed format.
  
 
[[Category:Packaging guidelines drafts]]
 
[[Category:Packaging guidelines drafts]]
Line 22: Line 22:
 
%package doc
 
%package doc
 
Summary: Documentation for ###package-Summary###
 
Summary: Documentation for ###package-Summary###
 +
License: ###may-be-different-such-as-GFDL###
 
Group: Documentation
 
Group: Documentation
 
BuildArch: noarch
 
BuildArch: noarch
Line 32: Line 33:
 
%files doc
 
%files doc
 
%doc ###path-in-build-dir###/###manual1###.html
 
%doc ###path-in-build-dir###/###manual1###.html
 +
%doc ###path-in-build-dir###/###manual1###.pdf
 
%doc ###path-in-build-dir###/###manual2###.html
 
%doc ###path-in-build-dir###/###manual2###.html
 +
%doc ###path-in-build-dir###/###manual2###.pdf
 
%defattr(-,root,root)
 
%defattr(-,root,root)
 
%{_infodir}/###manual1###.info*
 
%{_infodir}/###manual1###.info*
 
%{_infodir}/###manual2###.info*
 
%{_infodir}/###manual2###.info*
 
</pre>
 
</pre>

Latest revision as of 15:45, 15 February 2011

Contents

[edit] HTML preferred over INFO

GNU packages have documentation provided as texinfo files. These can be translated into (the most popular ones) info, html (in single-page or multi-page format), pdf or plain text. Currently only info documents are generated.

There was a suggestion users nowadays prefer more for example html than the info documents. It is an idea derived from Jan Pazdziora's man page format suggestion, although the man page target format is not applicable to the texinfo source format.

[edit] Proposal

While info documents should remain available proposing to also generate single-page html format and the pdf format.

As info is normally stored compressed (.info.gz, 411KB) it is much smaller than .html (2280KB). Therefore proposing to move both all the info, html and pdf documentation into separate -doc subpackages. Man pages are generally available still in the main packages for the basic information.

[edit] Example

Package gdb-7.2.50.20110213-23.fc15 is now using the proposed format.

[edit] Implementation

%package doc
Summary: Documentation for ###package-Summary###
License: ###may-be-different-such-as-GFDL###
Group: Documentation
BuildArch: noarch

%description doc
###brief package description###

This package provides INFO and HTML user manual for ###package###.

%files doc
%doc ###path-in-build-dir###/###manual1###.html
%doc ###path-in-build-dir###/###manual1###.pdf
%doc ###path-in-build-dir###/###manual2###.html
%doc ###path-in-build-dir###/###manual2###.pdf
%defattr(-,root,root)
%{_infodir}/###manual1###.info*
%{_infodir}/###manual2###.info*