El vie, 04-01-2013 a las 23:34 -0600, Donnie Berkholz escribió: > On 10:26 Sat 22 Dec , Pacho Ramos wrote: > > Hello > > > > After seeing: > > https://bugs.gentoo.org/show_bug.cgi?id=440214 > > > > Looking to a lot of its blockers shows that we are using "elog" messages > > for informing people about configuration (like pointing people to > > external links to get proper way of configuring things, tell them to add > > to some system groups...). I thought that maybe this kind of information > > could be simply included in a canonical file under /usr/share/doc/ > > package dir called, for example, CONFIGURATION or SETUP. We would them > > point people (now with a news item, for the long term provably a note to > > handbook to newcomers would be nice) to that file to configure their > > setups. The main advantages I see: > > - We will flood less summary.log ;) > > - The information to configure the package is always present while > > package is installed, now, if we remove merge produced logs, people will > > need to reemerge the package or read directly the ebuild > > > > What do you think? > > Bikeshedding ... would go with README.gentoo, because people are already > used to looking for README files. Every time we can eliminate > Gentoo-specific weirdness, we should. >
This will install a README.gentoo file
But there are still pending issues I don't know how to handle:
- Eclass was originally oriented to cover those kind of messages that
could be shown by elog first time the package is merged and, later, rely
on people reading that README.gentoo
- William asked for version checking support, in that case, what kind of
version checking should be covered?
- Should I rely on versionator.eclass or use ">/<"? I can see both forms
in the tree right now
- There are also a lot of "exotic" version checkings in the tree (please
grep looking for REPLACING_VERSIONS to see them) that I doubt we should
cover in eclass but, in that case, how to cover them also?
- A suggestion about looking for "${FILESDIR}/README.gentoo" has also
raised, in that case, should eclass look for either option (now
DOC_CONTENTS variable or "${FILESDIR}/README.gentoo")
# Copyright 1999-2012 Gentoo Foundation
# Distributed under the terms of the GNU General Public License v2
# $Header: $
# @ECLASS: configuration-doc
# @MAINTAINER:
# Pacho Ramos <pa...@gentoo.org>
# @AUTHOR:
# Author: Pacho Ramos <pa...@gentoo.org>
# @BLURB: An eclass for installing a README.gentoo doc file recording tips
# shown via elog messages. With this eclass, those elog messages will only be
# shown at first package installation and a file for later reviewing will be
# installed under /usr/share/doc/${PF}
# @DESCRIPTION:
# An eclass for installing a README.gentoo doc file recording tips
# shown via elog messages. With this eclass, those elog messages will only be
# shown at first package installation and a file for later reviewing will be
# installed under /usr/share/doc/${PF}
if [[ ${___ECLASS_ONCE_CONFIGURATION_DOC} != "recur -_+^+_- spank" ]] ; then
___ECLASS_ONCE_CONFIGURATION_DOC="recur -_+^+_- spank"
inherit eutils
case "${EAPI:-0}" in
0|1|2|3)
die "Unsupported EAPI=${EAPI:-0} (too old) for ${ECLASS}"
;;
4|5)
# EAPI>=4 is required for REPLACING_VERSIONS preventing us
# from needing to export another pkg_preinst phase to save
has_version
# result. Also relies on EAPI >=4 default src_install phase.
;;
*)
die "Unsupported EAPI=${EAPI} (unknown) for ${ECLASS}"
;;
esac
EXPORT_FUNCTIONS src_install pkg_postinst
# @FUNCTION: configuration_create_doc
# @DESCRIPTION:
# Create doc file with DOC_CONTENTS contents.
# Usually called at src_install phase.
configuration_create_doc() {
debug-print-function ${FUNCNAME} "${@}"
if [[ -n "${DOC_CONTENTS}" ]]; then
eshopts_push
set -f
echo ${DOC_CONTENTS} | fmt > "${T}"/README.gentoo
eshopts_pop
dodoc "${T}"/README.gentoo
fi
}
# @FUNCTION: configuration_print_elog
# @DESCRIPTION:
# Print elog messages with DOC_CONTENTS contents.
# Usually called at pkg_postinst phase.
configuration_print_elog() {
debug-print-function ${FUNCNAME} "${@}"
if [[ -n "${DOC_CONTENTS}" ]]; then
if ! [[ "${REPLACING_VERSIONS}" ]]; then
eshopts_push
set -f
if [ -f "${T}"/README.gentoo ]; then
echo ${DOC_CONTENTS} | fmt | while read -r
ELINE; do elog "${ELINE}"; done
else
die ""${T}"/README.gentoo is missing, did you
forget to call configuration_create_doc function?"
fi
eshopts_pop
fi
fi
}
# @FUNCTION: configuration-doc_src_install
# @DESCRIPTION:
# Show elog messages from DOC_CONTENTS variable, that will be
# shared with /usr/share/doc/${PF}/README.gentoo content.
configuration-doc_src_install() {
debug-print-function ${FUNCNAME} "${@}"
default
configuration_create_doc
}
# @FUNCTION: configuration-doc_pkg_postinst
# @DESCRIPTION:
# Show elog messages from DOC_CONTENTS variable, that will be
# shared with /usr/share/doc/${PF}/README.gentoo content.
configuration-doc_pkg_postinst() {
debug-print-function ${FUNCNAME} "${@}"
configuration_print_elog
}
fi
signature.asc
Description: This is a digitally signed message part
