Opened 17 years ago
Closed 14 years ago
#3798 closed enhancement (wontfix)
Install user documentation during normal installation
Reported by: | Owned by: | Robert Kulagowski | |
---|---|---|---|
Priority: | minor | Milestone: | unknown |
Component: | Documentation | Version: | head |
Severity: | medium | Keywords: | user documentation install |
Cc: | Ticket locked: | no |
Description
Attached is a patch to install the documentation in mythtv/docs during a normal install.
There are two new configure pairs:
- --enable-user-docbuild, --disable-user-docbuild
- --enable-dev-docbuild, --disable-dev-docbuild
Install Dir:
- The install dir is $(PREFIX)/share/doc/mythtv
User Docs:
- User documentation is under version control and exists in a fresh checkout.
- User docs will always be installed
- A make clean will not normally remove the prebuilt user docs
- If the --enable-user-docbuild is spec'd (and the prereqs are available) the user docs will be built during a "make install" and cleaned during a "make clean"
Dev Docs:
- The dev docs are built and installed if --enable-dev-docbuild is spec'd
- Even if --enable-dev-docbuild is not spec'd at configure the dev-docs can be built and installed later with a "make devdocs && make install_devdocs"
There are other make targets to be able to install/uninstall/clean the dev or user docs without the need to reconfigure the entire myth project.
Please let me know if any changes need to be made.
Roo.
PS: This is not in the form of a qmake docs.pro as qmake sucks for this doco type setup, spent some time on the #qt channel but it is buggy when using the custom objects.
Attachments (3)
Change History (21)
Changed 17 years ago by
Attachment: | mythtv_docs_v1.diff added |
---|
comment:1 Changed 17 years ago by
Seems my testing wasn't complete, I just run a make distclean from the mythtv directory and it removed the Makefile from the docs dir. This broke the build system.
Maybe this needs to be done with qmake docs.pro after all. I will look further into it.
PS: This sucks as I thought I tested this, sorry for creating this ticket for a broken patch (at the moment).
Changed 17 years ago by
Attachment: | mythtv_docs_v2.diff added |
---|
V2 using qmake, this replaces v1 of the patch
comment:2 Changed 17 years ago by
I have reworked the patch, because as mentioned in a previous comment the Makefile version did not play well with qmake.
Most of the commentry in the description is still accurate, except there aren't the number of additional targets.
The configure options --dis/enable-dev-docbuild and --des/enable-user-docbuild are used. If --user-docbuild option is not specified the user docs will just be installed and not rebuilt from the .sgml.
If --dis/enable-dev-docbuild option is used then the dev-docs will be built and install when myth is built and installed. If it is not specified the user can still "make dev-docs" to build the doxygen documentation without the need to reconfigure mythtv.
Due to the limitations of svn diff the following steps are also needed:
- svn add docs/docs.pro
- svn propedit svn:ignore docs - add "Makefile", "dummy", "dummy.o", "validate"
- svn cp themes/dummy.c docs
- svn rm docs/Makefile
- svn rm docs/mythtv-HOWTO.html
This patch also uses "tee" for logging the validate output to file as well a displaying it. I believe tee should be part of most distros.
The docs install dir does not contain any version info, this is consistent with the other install dirs and there shouldn't be multiple installed versions of myth anyway (I believe).
Roo.
comment:3 Changed 17 years ago by
With the bugs I have experienced with qmake I should record the version I am using:
cameron@pegasus:~$ qmake --version Qmake version: 1.07a (Qt 3.3.7) Qmake is free software from Trolltech AS.
Roo
comment:4 Changed 17 years ago by
If this is accepted, mythtv/keys.txt could get moved to mythtv/docs/default_keys.txt and add
USER_INSTALLS += default_keys.txt
to the docs.pro.
As far as I am aware keys.txt is documentation only, if not another approach may be needed.
comment:5 Changed 17 years ago by
Component: | mythtv → documentation |
---|---|
Owner: | changed from Isaac Richards to Robert Tsai |
comment:6 Changed 17 years ago by
Owner: | changed from Robert Tsai to Isaac Richards |
---|
comment:7 Changed 16 years ago by
Owner: | changed from Isaac Richards to danielk |
---|---|
Status: | new → assigned |
comment:8 Changed 16 years ago by
Milestone: | 0.21 → 0.22 |
---|---|
Status: | assigned → infoneeded |
patch no longer applies, can you update this to head?
comment:9 Changed 16 years ago by
I have updated the patch, will attach v3a shortly.
If you enable the user doc build you will see the following error:
troff: fatal error: can't find macro file s
The error also occurs when building the user docs from the sgml. Users won't see this normally as there is no need to build the user docs as they are under VC (hence the --enable-users-docs configure option not being listed in the --help output).
comment:10 Changed 16 years ago by
Would a version of this patch be considered for 0.21 that only installed the user documentation?
ie. Didn't have the userdoc build option to configure (which may be not be needed anyway) or the the dev-docs configure option.
Even without the configure options you can still build the user and dev docs from the docs dir with a "make dev-docs" or "make mythtv-HOWTO.pdf" etc.
comment:11 Changed 16 years ago by
Status: | infoneeded → assigned |
---|
comment:12 Changed 15 years ago by
Stuart, I've looked at this and I'm not sure it's a good idea as is. If we want to apply this we should remove the docs/mythtv-HOWTO*.html files and add them and the docs/dummy.c to the svn:ignore list for the docs directory.
comment:13 Changed 15 years ago by
Owner: | changed from danielk to stuartm |
---|
comment:14 Changed 15 years ago by
Owner: | stuartm deleted |
---|---|
Status: | assigned → new |
comment:15 Changed 15 years ago by
Owner: | set to Robert Kulagowski |
---|---|
Status: | new → assigned |
comment:16 Changed 15 years ago by
Component: | documentation → Documentation |
---|---|
Milestone: | 0.22 → 0.23 |
comment:17 Changed 14 years ago by
Milestone: | 0.23 → unknown |
---|
This doesn't seem likely to get done for .23, bumping to unknown until someone picks it up.
comment:18 Changed 14 years ago by
Resolution: | → wontfix |
---|---|
Status: | assigned → closed |
Doesn't seem to be any chance that this will happen, nor does the patch show any signs of life.
V1 of the documentation installer