We have none. :)
In the past I mentioned my background in technical writing and an interest in coordinating a user's guide. No promises but I want to get something moving.
I have PDF copies of three KDE3 user guides. All are licensed to allow using the text in other documents.
KDEUserGuideFinal.pdf: Published by the United Nations Development Programme’s Asia-Pacific Development Information Programme (UNDP-APDIP)Kuala Lumpur, Malaysia (heavily focused on PCLinuxOS)
opensuse110_kdequick.pdf
opensuse110_kdeuser.pdf
Although I could convert those documents to text files with various conversion tools, I would like to find the original source files. For you OpenSuse folks, you might be able to find those two document source files.
The Kubuntu people at one time had a KDE 3 user's guide. I can find HTML remnants of such a guide on the web.
Tim, as the one-time Kubuntu coordinator for KDE3 I'm hoping you might be able to find sources for that document.
Long term I want to establish a process to single source the text to various mediums: a PDF, HTML, wiki, etc. Single sourcing text files long been has the Holy Grail of technical writing and frankly, no optimal solution yet exists despite what anybody might claim. DocBook, DITA, XML all were supposed to provide that single source miracle but none have fulfilled any tech writer's dream. Nonetheless, if we get our hands on the original source files for these documents we then find a big step in the right direction toward providing a much-needed Trinity user's guide. If not we still can convert the information using raw conversion tools.
Thanks!
Darrell
On Wednesday 16 November 2011 11:12:43 am Darrell Anderson wrote:
We have none. :)
In the past I mentioned my background in technical writing and an interest in coordinating a user's guide. No promises but I want to get something moving.
I have PDF copies of three KDE3 user guides. All are licensed to allow using the text in other documents.
KDEUserGuideFinal.pdf: Published by the United Nations Development Programme’s Asia-Pacific Development Information Programme (UNDP-APDIP)Kuala Lumpur, Malaysia (heavily focused on PCLinuxOS)
opensuse110_kdequick.pdf
opensuse110_kdeuser.pdf
Although I could convert those documents to text files with various conversion tools, I would like to find the original source files. For you OpenSuse folks, you might be able to find those two document source files.
The Kubuntu people at one time had a KDE 3 user's guide. I can find HTML remnants of such a guide on the web.
Tim, as the one-time Kubuntu coordinator for KDE3 I'm hoping you might be able to find sources for that document.
Long term I want to establish a process to single source the text to various mediums: a PDF, HTML, wiki, etc. Single sourcing text files long been has the Holy Grail of technical writing and frankly, no optimal solution yet exists despite what anybody might claim. DocBook, DITA, XML all were supposed to provide that single source miracle but none have fulfilled any tech writer's dream. Nonetheless, if we get our hands on the original source files for these documents we then find a big step in the right direction toward providing a much-needed Trinity user's guide. If not we still can convert the information using raw conversion tools.
Thanks!
Darrell
I might not be a technical writer, but I've written a few mini-guides and I'm still newbie enough to work up some sensible rough drafts. I generally don't like using someone else's guides, partly because I'm too lazy to take the time to read them, and I tend to be a real stickler for grammar, detail, and easy to follow directions ;-)
If you are going to use the PDFs, we might be able to coordinate, perhaps get more people involved. My only problem is if we use the wiki, there have been some complaints about the way it saves the markups and then converts them to a different markup format, memorizing one markup is hard enough without having to juggle two on one wiki.
-- Kristopher Gamrat Ark Linux webmaster http://www.arklinux.org/
Hi Darrell
You might check out Scrivener (http://www.literatureandlatte.com/) it is a writers tool for correlating and organizing your documents and then exporting them into different file formats. It also allows importing research documents (html, pdf, web links, etc) that you can reference from inside Scrivener (i.e. your older KDE3 documentation) while you are editing or writing your documentation.
They have Mac, Windows and Linux versions, but...
The Mac version (vs 2.0) "may" do what you want, it is the most advanced and well tested but I don't have a Mac and haven't used it.
The Windows version (vs 1.0) which was just released, does OK with the exported formats but the HTML code it exports is messy and hard to edit...
The Linux version (Beta vs 0.4) "may" be far enough along to work for what you need--and it is free for now.
I use the Windows version in a VirtualBox XP setup for my documenting and general writing work.
The basic Idea is that you write or import the text and store it as a project in Scrivener. Then you use the export features to output PDF, ePub, Word, HTML and other formats. You can do basic word processing style formating inside Scrivener and it is carried through to the exported documents.
It is payware and it is the first software I have bought in years AND the first Windows program that I have used in 12 years--that should show how much I like it.
Keith
On Wed, Nov 16, 2011 at 11:12 AM, Darrell Anderson humanreadable@yahoo.com wrote:
We have none. :)
In the past I mentioned my background in technical writing and an interest in coordinating a user's guide. No promises but I want to get something moving.
I have PDF copies of three KDE3 user guides. All are licensed to allow using the text in other documents.
KDEUserGuideFinal.pdf: Published by the United Nations Development Programme’s Asia-Pacific Development Information Programme (UNDP-APDIP)Kuala Lumpur, Malaysia (heavily focused on PCLinuxOS)
opensuse110_kdequick.pdf
opensuse110_kdeuser.pdf
Although I could convert those documents to text files with various conversion tools, I would like to find the original source files. For you OpenSuse folks, you might be able to find those two document source files.
The Kubuntu people at one time had a KDE 3 user's guide. I can find HTML remnants of such a guide on the web.
Tim, as the one-time Kubuntu coordinator for KDE3 I'm hoping you might be able to find sources for that document.
Long term I want to establish a process to single source the text to various mediums: a PDF, HTML, wiki, etc. Single sourcing text files long been has the Holy Grail of technical writing and frankly, no optimal solution yet exists despite what anybody might claim. DocBook, DITA, XML all were supposed to provide that single source miracle but none have fulfilled any tech writer's dream. Nonetheless, if we get our hands on the original source files for these documents we then find a big step in the right direction toward providing a much-needed Trinity user's guide. If not we still can convert the information using raw conversion tools.
Thanks!
Darrell
To unsubscribe, e-mail: trinity-devel-unsubscribe@lists.pearsoncomputing.net For additional commands, e-mail: trinity-devel-help@lists.pearsoncomputing.net Read list messsages on the Web archive: http://trinity-devel.pearsoncomputing.net/ Please remember not to top-post: http://trinity.pearsoncomputing.net/mailing_lists/#top-posting
On 16 November 2011 12:04, Keith Daniels keithwdaniels@gmail.com wrote:
Hi Darrell
You might check out Scrivener (http://www.literatureandlatte.com/) it is a writers tool for correlating and organizing your documents and then exporting them into different file formats. It also allows importing research documents (html, pdf, web links, etc) that you can reference from inside Scrivener (i.e. your older KDE3 documentation) while you are editing or writing your documentation.
They have Mac, Windows and Linux versions, but...
The Mac version (vs 2.0) "may" do what you want, it is the most advanced and well tested but I don't have a Mac and haven't used it.
The Windows version (vs 1.0) which was just released, does OK with the exported formats but the HTML code it exports is messy and hard to edit...
The Linux version (Beta vs 0.4) "may" be far enough along to work for what you need--and it is free for now.
I use the Windows version in a VirtualBox XP setup for my documenting and general writing work.
The basic Idea is that you write or import the text and store it as a project in Scrivener. Then you use the export features to output PDF, ePub, Word, HTML and other formats. You can do basic word processing style formating inside Scrivener and it is carried through to the exported documents.
It is payware and it is the first software I have bought in years AND the first Windows program that I have used in 12 years--that should show how much I like it.
Keith
On Wed, Nov 16, 2011 at 11:12 AM, Darrell Anderson humanreadable@yahoo.com wrote:
We have none. :)
In the past I mentioned my background in technical writing and an
interest in coordinating a user's guide. No promises but I want to get something moving.
I have PDF copies of three KDE3 user guides. All are licensed to allow
using the text in other documents.
KDEUserGuideFinal.pdf: Published by the United Nations Development
Programme’s Asia-Pacific Development Information Programme (UNDP-APDIP)Kuala Lumpur, Malaysia (heavily focused on PCLinuxOS)
opensuse110_kdequick.pdf
opensuse110_kdeuser.pdf
Although I could convert those documents to text files with various
conversion tools, I would like to find the original source files. For you OpenSuse folks, you might be able to find those two document source files.
The Kubuntu people at one time had a KDE 3 user's guide. I can find HTML
remnants of such a guide on the web.
Tim, as the one-time Kubuntu coordinator for KDE3 I'm hoping you might
be able to find sources for that document.
Long term I want to establish a process to single source the text to
various mediums: a PDF, HTML, wiki, etc. Single sourcing text files long been has the Holy Grail of technical writing and frankly, no optimal solution yet exists despite what anybody might claim. DocBook, DITA, XML all were supposed to provide that single source miracle but none have fulfilled any tech writer's dream. Nonetheless, if we get our hands on the original source files for these documents we then find a big step in the right direction toward providing a much-needed Trinity user's guide. If not we still can convert the information using raw conversion tools.
Thanks!
Darrell
Why not just use basic markup like markdown for example.
Then check it into a git repository so we can track changes (most important part)
Then use conversion utilities to export it into different document types.
I dunno that's what I'd do:)
On Wed, Nov 16, 2011 at 15:45, Calvin Morrison mutantturkey@gmail.com wrote:
Why not just use basic markup like markdown for example.
Then check it into a git repository so we can track changes (most important part)
Then use conversion utilities to export it into different document types.
I dunno that's what I'd do:)
Right now, I think the wiki is ok. If we needed a very official looking user guide, I'd suggest the same thing Github wikis use :)
On 16 November 2011 12:04, Keith Daniels keithwdaniels@gmail.com wrote:
Hi Darrell
You might check out Scrivener (http://www.literatureandlatte.com/) it is a writers tool for correlating and organizing your documents and then exporting them into different file formats. It also allows importing research documents (html, pdf, web links, etc) that you can reference from inside Scrivener (i.e. your older KDE3 documentation) while you are editing or writing your documentation.
They have Mac, Windows and Linux versions, but...
The Mac version (vs 2.0) "may" do what you want, it is the most advanced and well tested but I don't have a Mac and haven't used it.
The Windows version (vs 1.0) which was just released, does OK with the exported formats but the HTML code it exports is messy and hard to edit...
The Linux version (Beta vs 0.4) "may" be far enough along to work for what you need--and it is free for now.
I use the Windows version in a VirtualBox XP setup for my documenting and general writing work.
The basic Idea is that you write or import the text and store it as a project in Scrivener. Then you use the export features to output PDF, ePub, Word, HTML and other formats. You can do basic word processing style formating inside Scrivener and it is carried through to the exported documents.
It is payware and it is the first software I have bought in years AND the first Windows program that I have used in 12 years--that should show how much I like it.
Keith
On Wed, Nov 16, 2011 at 11:12 AM, Darrell Anderson humanreadable@yahoo.com wrote:
We have none. :)
In the past I mentioned my background in technical writing and an
interest in coordinating a user's guide. No promises but I want to get something moving.
I have PDF copies of three KDE3 user guides. All are licensed to allow
using the text in other documents.
KDEUserGuideFinal.pdf: Published by the United Nations Development
Programmes Asia-Pacific Development Information Programme (UNDP-APDIP)Kuala Lumpur, Malaysia (heavily focused on PCLinuxOS)
opensuse110_kdequick.pdf
opensuse110_kdeuser.pdf
Although I could convert those documents to text files with various
conversion tools, I would like to find the original source files. For you OpenSuse folks, you might be able to find those two document source files.
The Kubuntu people at one time had a KDE 3 user's guide. I can find
HTML remnants of such a guide on the web.
Tim, as the one-time Kubuntu coordinator for KDE3 I'm hoping you might
be able to find sources for that document.
Long term I want to establish a process to single source the text to
various mediums: a PDF, HTML, wiki, etc. Single sourcing text files long been has the Holy Grail of technical writing and frankly, no optimal solution yet exists despite what anybody might claim. DocBook, DITA, XML all were supposed to provide that single source miracle but none have fulfilled any tech writer's dream. Nonetheless, if we get our hands on the original source files for these documents we then find a big step in the right direction toward providing a much-needed Trinity user's guide. If not we still can convert the information using raw conversion tools.
Thanks!
Darrell
Why not just use basic markup like markdown for example.
Then check it into a git repository so we can track changes (most important part)
Then use conversion utilities to export it into different document types.
I dunno that's what I'd do:)
I would definitely encourage the usage of an open format flat file (or files), such as fodt or some sort of Latex format, in the GIT repository. This would greatly simplify differences between versions (if needed), and thereby make it easier for those without write access to GIT to jump in, edit the document, and submit a patch with their additions.
And I would really like to see this idea take off for R14.0! This is one area where we can really shine compared to other desktops out there.
Tim
On Wednesday 16 November 2011 03:51:01 pm Timothy Pearson wrote:
I would definitely encourage the usage of an open format flat file (or files), such as fodt or some sort of Latex format, in the GIT repository. This would greatly simplify differences between versions (if needed), and thereby make it easier for those without write access to GIT to jump in, edit the document, and submit a patch with their additions.
Not everybody will have a Latex editor at the ready. I don't know what fodt is. Most people will have an ODT-compatible editor such as LibreOffice or AbiWord (I think even MS Office can read/save ODT files since their 2007 edition).
On Wednesday 16 November 2011 03:51:01 pm Timothy Pearson wrote:
I would definitely encourage the usage of an open format flat file (or files), such as fodt or some sort of Latex format, in the GIT repository. This would greatly simplify differences between versions (if needed), and thereby make it easier for those without write access to GIT to jump in, edit the document, and submit a patch with their additions.
Not everybody will have a Latex editor at the ready. I don't know what fodt is. Most people will have an ODT-compatible editor such as LibreOffice or AbiWord (I think even MS Office can read/save ODT files since their 2007 edition).
fodt is the Flat ODT format, which OpenOffice/LibreOffice can read and write natively. The advantage over ODT is that it is not a binary blob, so it doesn't take up massive amounts of space in our SCM, and patches can be made/applied (this is important in a collaborative environment outside of something like Etherpad).
Tim
I would definitely encourage the usage of an open
format flat file (or
files), such as fodt or some sort of Latex format,
in the GIT
repository. This would greatly simplify differences between
versions (if needed),
and thereby make it easier for those without write
access to GIT to jump in,
edit the document, and submit a patch with their
additions.
Not everybody will have a Latex editor at the ready. I
don't know what
fodt is. Most people will have an ODT-compatible editor
such as LibreOffice or
AbiWord (I think even MS Office can read/save ODT
files since their 2007
edition).
fodt is the Flat ODT format, which OpenOffice/LibreOffice can read and write natively. The advantage over ODT is that it is not a binary blob, so it doesn't take up massive amounts of space in our SCM, and patches can be made/applied (this is important in a collaborative environment outside of something like Etherpad).
There are several responses to my original query about a user guide. I'll use this most recent reply to respond.
Side comment: I want to produce something for R14. Something.
There are two aspects to this discussion. The second part can be split into two components.
One aspect is the formats we want to produce. The other is the tools we use. Within this latter area we have the desire to produce professional user guides. We also need to maintain TDE Help files, much of which are long overdue for reviews and updating.
A) Formats:
HTML and PDF. These formats are portable and do not require being connected to the web. The HTML version may be duplicated at the web site and is easy to slip into a distro's desktop. PDF is useful for studying without flip-flopping around computer screens because they are designed for printing.
B) Tool chains:
1) User guides? How do other groups support both formats? Docbook is somewhat popular but a custom post processing tool chain is needed to produce quality professional output. This post processing tool chain is not easy to create or use. Additional challenge: few people like editing in a raw markup language, which discourages people from helping.
2) Help files: they are in Docbook. I don't believe we need to perform any post processing on these files. I believe the underlying viewing engine does that on-the-fly. These files can be edited and merged upstream like software patches. Yet we still need to edit in raw markup. Is there a better way?
More to consider:
Do we want to showcase Trinity and use only tools provided by Trinity to maintain the user guides and Help files? What is the perception by others if we uses tools not in Trinity?
Tools like Latex are useful to a minority of people, but tools like that will not be adopted by the typical person who wants to help with documentation. What tools do we use to encourage others to help and participate? Do we need a two step process (writer to editor) with respect to other people participating?
With the user guides we want to modularize information --- something commonly called master documents. In the proprietary world MS Word and Adobe FrameMaker support this concept. I think LibreOffice Writer does (but Writer is not a Trinity app). I don't know whether KWord supports the feature although KWord supports ODT.
Traditionally word processors support PDF exporting quite well but produce horrible non-validating HTML. Has this changed?
Darrell
On 16 November 2011 22:00, Darrell Anderson humanreadable@yahoo.com wrote:
I would definitely encourage the usage of an open
format flat file (or
files), such as fodt or some sort of Latex format,
in the GIT
repository. This would greatly simplify differences between
versions (if needed),
and thereby make it easier for those without write
access to GIT to jump in,
edit the document, and submit a patch with their
additions.
Not everybody will have a Latex editor at the ready. I
don't know what
fodt is. Most people will have an ODT-compatible editor
such as LibreOffice or
AbiWord (I think even MS Office can read/save ODT
files since their 2007
edition).
fodt is the Flat ODT format, which OpenOffice/LibreOffice can read and write natively. The advantage over ODT is that it is not a binary blob, so it doesn't take up massive amounts of space in our SCM, and patches can be made/applied (this is important in a collaborative environment outside of something like Etherpad).
There are several responses to my original query about a user guide. I'll use this most recent reply to respond.
Side comment: I want to produce something for R14. Something.
There are two aspects to this discussion. The second part can be split into two components.
One aspect is the formats we want to produce. The other is the tools we use. Within this latter area we have the desire to produce professional user guides. We also need to maintain TDE Help files, much of which are long overdue for reviews and updating.
A) Formats:
HTML and PDF. These formats are portable and do not require being connected to the web. The HTML version may be duplicated at the web site and is easy to slip into a distro's desktop. PDF is useful for studying without flip-flopping around computer screens because they are designed for printing.
B) Tool chains:
- User guides? How do other groups support both formats? Docbook is
somewhat popular but a custom post processing tool chain is needed to produce quality professional output. This post processing tool chain is not easy to create or use. Additional challenge: few people like editing in a raw markup language, which discourages people from helping.
- Help files: they are in Docbook. I don't believe we need to perform any
post processing on these files. I believe the underlying viewing engine does that on-the-fly. These files can be edited and merged upstream like software patches. Yet we still need to edit in raw markup. Is there a better way?
More to consider:
Do we want to showcase Trinity and use only tools provided by Trinity to maintain the user guides and Help files? What is the perception by others if we uses tools not in Trinity?
Tools like Latex are useful to a minority of people, but tools like that will not be adopted by the typical person who wants to help with documentation. What tools do we use to encourage others to help and participate? Do we need a two step process (writer to editor) with respect to other people participating?
With the user guides we want to modularize information --- something commonly called master documents. In the proprietary world MS Word and Adobe FrameMaker support this concept. I think LibreOffice Writer does (but Writer is not a Trinity app). I don't know whether KWord supports the feature although KWord supports ODT.
Traditionally word processors support PDF exporting quite well but produce horrible non-validating HTML. Has this changed?
Darrell
To unsubscribe, e-mail: trinity-devel-unsubscribe@lists.pearsoncomputing.net For additional commands, e-mail: trinity-devel-help@lists.pearsoncomputing.net Read list messsages on the Web archive: http://trinity-devel.pearsoncomputing.net/ Please remember not to top-post: http://trinity.pearsoncomputing.net/mailing_lists/#top-posting
Personally,
I think PDF is crap. Totally crap. 100% crap. Closed Proprietary locked down garbage. Also not friendly to content management systems.
Markdown is really easy, and it is easy to output into many formats. It's similar to wikipedia's markup. I suggest we use markdown. it's easy and not hard to learn, also it's flat file.
https://en.wikipedia.org/wiki/Markdown
Please read up on it. it's a lot less scary than learning html or dealing with PDF binary blobs.
Calvin Morrison
On Wednesday 16 November 2011 10:00:22 pm Darrell Anderson wrote:
There are several responses to my original query about a user guide. I'll use this most recent reply to respond.
Side comment: I want to produce something for R14. Something.
There are two aspects to this discussion. The second part can be split into two components.
One aspect is the formats we want to produce. The other is the tools we use. Within this latter area we have the desire to produce professional user guides. We also need to maintain TDE Help files, much of which are long overdue for reviews and updating.
A) Formats:
HTML and PDF. These formats are portable and do not require being connected to the web. The HTML version may be duplicated at the web site and is easy to slip into a distro's desktop. PDF is useful for studying without flip-flopping around computer screens because they are designed for printing.
B) Tool chains:
- User guides? How do other groups support both formats? Docbook is
somewhat popular but a custom post processing tool chain is needed to produce quality professional output. This post processing tool chain is not easy to create or use. Additional challenge: few people like editing in a raw markup language, which discourages people from helping.
- Help files: they are in Docbook. I don't believe we need to perform any
post processing on these files. I believe the underlying viewing engine does that on-the-fly. These files can be edited and merged upstream like software patches. Yet we still need to edit in raw markup. Is there a better way?
More to consider:
Do we want to showcase Trinity and use only tools provided by Trinity to maintain the user guides and Help files? What is the perception by others if we uses tools not in Trinity?
Tools like Latex are useful to a minority of people, but tools like that will not be adopted by the typical person who wants to help with documentation. What tools do we use to encourage others to help and participate? Do we need a two step process (writer to editor) with respect to other people participating?
With the user guides we want to modularize information --- something commonly called master documents. In the proprietary world MS Word and Adobe FrameMaker support this concept. I think LibreOffice Writer does (but Writer is not a Trinity app). I don't know whether KWord supports the feature although KWord supports ODT.
Traditionally word processors support PDF exporting quite well but produce horrible non-validating HTML. Has this changed?
I agree with the point of avoiding markup. There is a markup format that most people will be familiar with from Wikipedia, but a switch to MediaWiki seems unlikely, and not everybody will be comfortable with that.
I think most hard-core F\OSS users will want to avoid proprietary softwares, and not everybody can afford programs like MS Office. Yes, LibreOffice does have support for doc and docx formats, but I doubt it supports all features, that is not a garentee, and the only place I'd use the MS format is for my job anyway. Personally, I believe that since we're a F\OSS community, we should use F\OSS software and formats. I'd say it's acceptable to distribute PDFs of the finished guides, but I certainly think we should avoid them until then.
We're probably better off using either LibreOffice or KOffice. I don't think anybody will harp on us for using LibreOffice because of how widely-used it is, and how widely-used it's predecessor was. It's also open source, and it uses the same ODT format as KOffice. In fact, most open source editors support ODT, and I remember opening an ODT at school using MS Office 2007, before realizing that I forgot to convert it to their format, so anybody who does use MS Office should be able to contribute.
Another option is using an HTML IDE. Most open source ones produce plain HTML code without all the excessive meta tags. Some add a meta tag to identify the IDE, but otherwise just the code needed to properly display the page.
If we put the guides in their own section of git (I think that was mentioned earlier in this thread) and make that section read-only, that'll make it easier to keep track of the changes, collaborate, and revert in case of a mistake.
On 16 November 2011 22:46, Kristopher John Gamrat chaotickjg@gmail.comwrote:
On Wednesday 16 November 2011 10:00:22 pm Darrell Anderson wrote:
There are several responses to my original query about a user guide. I'll use this most recent reply to respond.
Side comment: I want to produce something for R14. Something.
There are two aspects to this discussion. The second part can be split
into
two components.
One aspect is the formats we want to produce. The other is the tools we use. Within this latter area we have the desire to produce professional user guides. We also need to maintain TDE Help files, much of which are long overdue for reviews and updating.
A) Formats:
HTML and PDF. These formats are portable and do not require being
connected
to the web. The HTML version may be duplicated at the web site and is
easy
to slip into a distro's desktop. PDF is useful for studying without flip-flopping around computer screens because they are designed for printing.
B) Tool chains:
- User guides? How do other groups support both formats? Docbook is
somewhat popular but a custom post processing tool chain is needed to produce quality professional output. This post processing tool chain is
not
easy to create or use. Additional challenge: few people like editing in a raw markup language, which discourages people from helping.
- Help files: they are in Docbook. I don't believe we need to perform
any
post processing on these files. I believe the underlying viewing engine does that on-the-fly. These files can be edited and merged upstream like software patches. Yet we still need to edit in raw markup. Is there a better way?
More to consider:
Do we want to showcase Trinity and use only tools provided by Trinity to maintain the user guides and Help files? What is the perception by others if we uses tools not in Trinity?
Tools like Latex are useful to a minority of people, but tools like that will not be adopted by the typical person who wants to help with documentation. What tools do we use to encourage others to help and participate? Do we need a two step process (writer to editor) with
respect
to other people participating?
With the user guides we want to modularize information --- something commonly called master documents. In the proprietary world MS Word and Adobe FrameMaker support this concept. I think LibreOffice Writer does
(but
Writer is not a Trinity app). I don't know whether KWord supports the feature although KWord supports ODT.
Traditionally word processors support PDF exporting quite well but
produce
horrible non-validating HTML. Has this changed?
I agree with the point of avoiding markup. There is a markup format that most people will be familiar with from Wikipedia, but a switch to MediaWiki seems unlikely, and not everybody will be comfortable with that.
I think most hard-core F\OSS users will want to avoid proprietary softwares, and not everybody can afford programs like MS Office. Yes, LibreOffice does have support for doc and docx formats, but I doubt it supports all features, that is not a garentee, and the only place I'd use the MS format is for my job anyway. Personally, I believe that since we're a F\OSS community, we should use F\OSS software and formats. I'd say it's acceptable to distribute PDFs of the finished guides, but I certainly think we should avoid them until then.
We're probably better off using either LibreOffice or KOffice. I don't think anybody will harp on us for using LibreOffice because of how widely-used it is, and how widely-used it's predecessor was. It's also open source, and it uses the same ODT format as KOffice. In fact, most open source editors support ODT, and I remember opening an ODT at school using MS Office 2007, before realizing that I forgot to convert it to their format, so anybody who does use MS Office should be able to contribute.
Another option is using an HTML IDE. Most open source ones produce plain HTML code without all the excessive meta tags. Some add a meta tag to identify the IDE, but otherwise just the code needed to properly display the page.
If we put the guides in their own section of git (I think that was mentioned earlier in this thread) and make that section read-only, that'll make it easier to keep track of the changes, collaborate, and revert in case of a mistake.
Kristopher Gamrat Ark Linux webmaster http://www.arklinux.org/
If you read up on markdown like I posted earlier you would realize markdown is almost identical to the Mediawiki style (format is almost the same, but it has the same ideas). Honestly Libreoffice is going to give us a binary blob as well as KOffice.
Markdown is just as easy as learning how to use libreoffice. The major advantages with markdown are:
1) Any editor works 2) Formatting can be learned in less than 10 minutes, similar to wikipedia 3) We can use Git to track changes in the repository 4) It is easy to convert into XML, PDF, whatever you like to publish. This makes it very versatile when considering options for distribution. 5) Readability, No nasty tags or hacks like HTML requires. No programming or web development knowledge.
Can you provide a similar list for LibreOffice? I'd like to pick the best option before we get to far in
Calvin Morrison
On 16 November 2011 22:46, Kristopher John Gamrat chaotickjg@gmail.comwrote:
On Wednesday 16 November 2011 10:00:22 pm Darrell Anderson wrote:
There are several responses to my original query about a user guide.
I'll
use this most recent reply to respond.
Side comment: I want to produce something for R14. Something.
There are two aspects to this discussion. The second part can be split
into
two components.
One aspect is the formats we want to produce. The other is the tools
we
use. Within this latter area we have the desire to produce
professional
user guides. We also need to maintain TDE Help files, much of which
are
long overdue for reviews and updating.
A) Formats:
HTML and PDF. These formats are portable and do not require being
connected
to the web. The HTML version may be duplicated at the web site and is
easy
to slip into a distro's desktop. PDF is useful for studying without flip-flopping around computer screens because they are designed for printing.
B) Tool chains:
- User guides? How do other groups support both formats? Docbook is
somewhat popular but a custom post processing tool chain is needed to produce quality professional output. This post processing tool chain
is not
easy to create or use. Additional challenge: few people like editing
in a
raw markup language, which discourages people from helping.
- Help files: they are in Docbook. I don't believe we need to perform
any
post processing on these files. I believe the underlying viewing
engine
does that on-the-fly. These files can be edited and merged upstream
like
software patches. Yet we still need to edit in raw markup. Is there a better way?
More to consider:
Do we want to showcase Trinity and use only tools provided by Trinity
to
maintain the user guides and Help files? What is the perception by
others
if we uses tools not in Trinity?
Tools like Latex are useful to a minority of people, but tools like
that
will not be adopted by the typical person who wants to help with documentation. What tools do we use to encourage others to help and participate? Do we need a two step process (writer to editor) with
respect
to other people participating?
With the user guides we want to modularize information --- something commonly called master documents. In the proprietary world MS Word and Adobe FrameMaker support this concept. I think LibreOffice Writer does
(but
Writer is not a Trinity app). I don't know whether KWord supports the feature although KWord supports ODT.
Traditionally word processors support PDF exporting quite well but
produce
horrible non-validating HTML. Has this changed?
I agree with the point of avoiding markup. There is a markup format that most people will be familiar with from Wikipedia, but a switch to MediaWiki seems unlikely, and not everybody will be comfortable with that.
I think most hard-core F\OSS users will want to avoid proprietary softwares, and not everybody can afford programs like MS Office. Yes, LibreOffice does have support for doc and docx formats, but I doubt it supports all features, that is not a garentee, and the only place I'd use the MS format is for my job anyway. Personally, I believe that since we're a F\OSS community, we should use F\OSS software and formats. I'd say it's acceptable to distribute PDFs of the finished guides, but I certainly think we should avoid them until then.
We're probably better off using either LibreOffice or KOffice. I don't think anybody will harp on us for using LibreOffice because of how widely-used it is, and how widely-used it's predecessor was. It's also open source, and it uses the same ODT format as KOffice. In fact, most open source editors support ODT, and I remember opening an ODT at school using MS Office 2007, before realizing that I forgot to convert it to their format, so anybody who does use MS Office should be able to contribute.
Another option is using an HTML IDE. Most open source ones produce plain HTML code without all the excessive meta tags. Some add a meta tag to identify the IDE, but otherwise just the code needed to properly display the page.
If we put the guides in their own section of git (I think that was mentioned earlier in this thread) and make that section read-only, that'll make it easier to keep track of the changes, collaborate, and revert in case of a mistake.
Kristopher Gamrat Ark Linux webmaster http://www.arklinux.org/
If you read up on markdown like I posted earlier you would realize markdown is almost identical to the Mediawiki style (format is almost the same, but it has the same ideas). Honestly Libreoffice is going to give us a binary blob as well as KOffice.
Markdown is just as easy as learning how to use libreoffice. The major advantages with markdown are:
- Any editor works
- Formatting can be learned in less than 10 minutes, similar to wikipedia
- We can use Git to track changes in the repository
- It is easy to convert into XML, PDF, whatever you like to publish. This
makes it very versatile when considering options for distribution. 5) Readability, No nasty tags or hacks like HTML requires. No programming or web development knowledge.
Can you provide a similar list for LibreOffice? I'd like to pick the best option before we get to far in
Calvin Morrison
LibreOffice can do all of the above, and more, as most of the computer literate world knows how to use a word processor.
We want to make it *easy* for people to contribute to the documentation. Any new language learning requirements, no matter how "simple", *will* cause people not to contribute.
Tim
On 16 November 2011 23:19, Timothy Pearson kb9vqf@pearsoncomputing.netwrote:
On 16 November 2011 22:46, Kristopher John Gamrat chaotickjg@gmail.comwrote:
On Wednesday 16 November 2011 10:00:22 pm Darrell Anderson wrote:
There are several responses to my original query about a user guide.
I'll
use this most recent reply to respond.
Side comment: I want to produce something for R14. Something.
There are two aspects to this discussion. The second part can be split
into
two components.
One aspect is the formats we want to produce. The other is the tools
we
use. Within this latter area we have the desire to produce
professional
user guides. We also need to maintain TDE Help files, much of which
are
long overdue for reviews and updating.
A) Formats:
HTML and PDF. These formats are portable and do not require being
connected
to the web. The HTML version may be duplicated at the web site and is
easy
to slip into a distro's desktop. PDF is useful for studying without flip-flopping around computer screens because they are designed for printing.
B) Tool chains:
- User guides? How do other groups support both formats? Docbook is
somewhat popular but a custom post processing tool chain is needed to produce quality professional output. This post processing tool chain
is not
easy to create or use. Additional challenge: few people like editing
in a
raw markup language, which discourages people from helping.
- Help files: they are in Docbook. I don't believe we need to perform
any
post processing on these files. I believe the underlying viewing
engine
does that on-the-fly. These files can be edited and merged upstream
like
software patches. Yet we still need to edit in raw markup. Is there a better way?
More to consider:
Do we want to showcase Trinity and use only tools provided by Trinity
to
maintain the user guides and Help files? What is the perception by
others
if we uses tools not in Trinity?
Tools like Latex are useful to a minority of people, but tools like
that
will not be adopted by the typical person who wants to help with documentation. What tools do we use to encourage others to help and participate? Do we need a two step process (writer to editor) with
respect
to other people participating?
With the user guides we want to modularize information --- something commonly called master documents. In the proprietary world MS Word and Adobe FrameMaker support this concept. I think LibreOffice Writer does
(but
Writer is not a Trinity app). I don't know whether KWord supports the feature although KWord supports ODT.
Traditionally word processors support PDF exporting quite well but
produce
horrible non-validating HTML. Has this changed?
I agree with the point of avoiding markup. There is a markup format that most people will be familiar with from Wikipedia, but a switch to MediaWiki seems unlikely, and not everybody will be comfortable with that.
I think most hard-core F\OSS users will want to avoid proprietary softwares, and not everybody can afford programs like MS Office. Yes, LibreOffice does have support for doc and docx formats, but I doubt it supports all features, that is not a garentee, and the only place I'd use the MS format is for my job anyway. Personally, I believe that since we're a F\OSS community, we should use F\OSS software and formats. I'd say it's acceptable to distribute PDFs of the finished guides, but I certainly think we should avoid them until then.
We're probably better off using either LibreOffice or KOffice. I don't think anybody will harp on us for using LibreOffice because of how widely-used it is, and how widely-used it's predecessor was. It's also open source, and it uses the same ODT format as KOffice. In fact, most open source editors support ODT, and I remember opening an ODT at school using MS Office 2007, before realizing that I forgot to convert it to their format, so anybody who does use MS Office should be able to contribute.
Another option is using an HTML IDE. Most open source ones produce plain HTML code without all the excessive meta tags. Some add a meta tag to identify the IDE, but otherwise just the code needed to properly display the page.
If we put the guides in their own section of git (I think that was mentioned earlier in this thread) and make that section read-only, that'll make it easier to keep track of the changes, collaborate, and revert in case of a mistake.
Kristopher Gamrat Ark Linux webmaster http://www.arklinux.org/
If you read up on markdown like I posted earlier you would realize markdown is almost identical to the Mediawiki style (format is almost the same,
but
it has the same ideas). Honestly Libreoffice is going to give us a binary blob as well as KOffice.
Markdown is just as easy as learning how to use libreoffice. The major advantages with markdown are:
- Any editor works
- Formatting can be learned in less than 10 minutes, similar to
wikipedia
- We can use Git to track changes in the repository
- It is easy to convert into XML, PDF, whatever you like to publish.
This
makes it very versatile when considering options for distribution. 5) Readability, No nasty tags or hacks like HTML requires. No programming or web development knowledge.
Can you provide a similar list for LibreOffice? I'd like to pick the best option before we get to far in
Calvin Morrison
LibreOffice can do all of the above, and more, as most of the computer literate world knows how to use a word processor.
We want to make it *easy* for people to contribute to the documentation. Any new language learning requirements, no matter how "simple", *will* cause people not to contribute.
Tim
OK Awesome!
(though my one quip is that while fodt is an "open" format, it is only supported by LibreOffice afaik)
Calvin Morrison
On Wednesday 16 November 2011 11:32:27 pm Calvin Morrison wrote:
- Readability, No nasty tags or hacks like HTML requires. No
programming or web development knowledge.
Can you provide a similar list for LibreOffice? I'd like to pick the best option before we get to far in
Calvin Morrison
LibreOffice can do all of the above, and more, as most of the computer literate world knows how to use a word processor.
We want to make it *easy* for people to contribute to the documentation. Any new language learning requirements, no matter how "simple", *will* cause people not to contribute.
Tim
OK Awesome!
(though my one quip is that while fodt is an "open" format, it is only supported by LibreOffice afaik)
I agree with Tim's point about avoiding markup, that was one of the points I made in my message.
The only thing I can't comment on is the HTML thing, I never used LibreOffice or OpenOffice for my HTML. I normally use a plain text editor for that. If LO doesn't produce clean HTML code, we could probably find a converter or HTML cleanup utility, or get a few people to help convert.
I'll reply to several posts here.
I referenced Word and FrameMaker only to illustrate the concept of "master documents." That is, merging multiple documents into one, basically by linking all documents into one and formatted with a master style sheet. My apologies for not explaining that I did not mean or intend we use them. :) As a tech writer I'm familiar with both but never would suggest such software for our project.
Both LibreOffice Writer and KWord support ODT, which fundamentally is XML. Exporting to PDF is straightforward with both. Actually, I just remembered (doh!) that TDE (KDE) natively supports printing to PDF through the KPrinter engine.
Word processors do provide binary blobs but is that a Bad Thing? We are discussing user guides, not forms of documentation that tend to change in real-time. Our user guides will be relatively static. We won't need version control.
One advantage about word processors is a low learning curve for people who want to help and participate. The traditional down side is HTML output is horrible. One would think with ODT, being based on XML, that HTML outputs would be a snap but that is not the case. Perhaps that has changed in the last year or so. I'll have to experiment a little.
There likely is a way to apply XSLT transforms to the underlying XML created in ODT. XSLT is what people in tech writing shops use when they use Docbook. The big challenge is creating an XSLT transform that provides a desired format. Not easy.
Since TDE natively supports printing to PDF, perhaps we should focus on appropriate solutions to support HTML. Perhaps somebody can write a cleanup script of sorts so the XML to HTML conversion validates correctly. With that we could use Writer or KWord. Does KWord support something similar to the "master document" concept?
People producing many of the popular distros all have pretty nice HTML documentation. What tools are those folks using to produce their HTML user guides?
Regarding PDF:
PDF is not proprietary (the specifications for producing PDF are open standards) but can be limited in application. PDFs suck on pocket e-readers, but they still work great on desktop computers. One of the cornerstones in writing is audience evaluation. The customer drives the process. PDF is a de facto standard for portability. We are dealing with end-users, mom-and-pops. Not all future Trinity users will be computer whiz kids. :) Mom and pops want to print documents. PDF lends well to that. HTML does not.
I browsed several links regarding Markdown. My resistance to markup languages is first, few people enjoy writing in that environment. Some people are exceptions --- perhaps this is a left-brain, right-brain thing. :) I dislike writing and editing in raw markup languages. I don't know whether I'm left-brained or right --- I'm just old and cantankerous. ;) Regardless, most people view writing in raw markup as inconvenient. WYSIWYG wins the day. :) Second, there is no immediate feedback with markup languages. Documents have to be validated and processed into the final output before anybody notices mistakes. That kind of process is fine for certain tasks but not for others. Third, simple markup languages start to break with complicated text flows, such as tables or professional text wrapping around images. Fourth, documents I have seen written in markup languages, such as Docbook, when converted to PDF are unprofessional looking. A common problem is paragraph headings that dangle at the bottom of a page rather than sticking with the subsequent paragraph. Of course, if we don't publish to PDF then I suppose we don't worry about that. :) Lastly, markup languages have to be validated and processed in some way to produce a desired output. That requires a processing engine. The more complicated the markup, the more complicated the processing engine.
LaTex probably is one of the best markup languages for finicky people. But few people want to write in a markup environment.
Another cornerstone with writing is if the tools are unpalatable to non geeks then the geeks gets stuck doing all the writing. :)
Darrell
On Thu, Nov 17, 2011 at 01:02, Darrell Anderson humanreadable@yahoo.com wrote:
I'll reply to several posts here.
I referenced Word and FrameMaker only to illustrate the concept of "master documents." That is, merging multiple documents into one, basically by linking all documents into one and formatted with a master style sheet. My apologies for not explaining that I did not mean or intend we use them. :) As a tech writer I'm familiar with both but never would suggest such software for our project.
Both LibreOffice Writer and KWord support ODT, which fundamentally is XML. Exporting to PDF is straightforward with both. Actually, I just remembered (doh!) that TDE (KDE) natively supports printing to PDF through the KPrinter engine.
Word processors do provide binary blobs but is that a Bad Thing? We are discussing user guides, not forms of documentation that tend to change in real-time. Our user guides will be relatively static. We won't need version control.
One advantage about word processors is a low learning curve for people who want to help and participate. The traditional down side is HTML output is horrible. One would think with ODT, being based on XML, that HTML outputs would be a snap but that is not the case. Perhaps that has changed in the last year or so. I'll have to experiment a little.
There likely is a way to apply XSLT transforms to the underlying XML created in ODT. XSLT is what people in tech writing shops use when they use Docbook. The big challenge is creating an XSLT transform that provides a desired format. Not easy.
Since TDE natively supports printing to PDF, perhaps we should focus on appropriate solutions to support HTML. Perhaps somebody can write a cleanup script of sorts so the XML to HTML conversion validates correctly. With that we could use Writer or KWord. Does KWord support something similar to the "master document" concept?
People producing many of the popular distros all have pretty nice HTML documentation. What tools are those folks using to produce their HTML user guides?
uh... SuSE uses NovDoc DTD, which is an enhanced version of DocBook DTD. IIRC many other distributions do the exact same thing. Fedora, for example, uses Publican, which is also an enhanced version of DocBook DTD.
(PS. I've just discovered that BerliOS isn't going to shut down after all. w00t!)
uh... SuSE uses NovDoc DTD, which is an enhanced version of DocBook DTD. IIRC many other distributions do the exact same thing. Fedora, for example, uses Publican, which is also an enhanced version of DocBook DTD.
Are you able to get your hands on that tool chain?
Darrell
On Thursday 17 November 2011 01:02:26 am Darrell Anderson wrote:
Word processors do provide binary blobs but is that a Bad Thing? We are discussing user guides, not forms of documentation that tend to change in real-time. Our user guides will be relatively static. We won't need version control.
I think the whole point of version control is to collaborate on the initial manuals. That would make it easier for everybody working on the same manual to stay up to date with each other, and also keep track of who did what in case we need to ask to clarify. Once the official documentation comes out, version control shouldn't be needed for documentation any more.
Yes,
But if we are suggesting that our users are incapable of editing markup of any kind, I seriously doubt their ability to use patch, diff, and git commands. On Nov 17, 2011 1:41 AM, "Kristopher John Gamrat" chaotickjg@gmail.com wrote:
On Thursday 17 November 2011 01:02:26 am Darrell Anderson wrote:
Word processors do provide binary blobs but is that a Bad Thing? We are discussing user guides, not forms of documentation that tend to change in real-time. Our user guides will be relatively static. We won't need
version
control.
I think the whole point of version control is to collaborate on the initial manuals. That would make it easier for everybody working on the same manual to stay up to date with each other, and also keep track of who did what in case we need to ask to clarify. Once the official documentation comes out, version control shouldn't be needed for documentation any more.
-- Kristopher Gamrat Ark Linux webmaster http://www.arklinux.org/
On Wednesday 16 November 2011 22:05:59 Kristopher John Gamrat wrote:
On Wednesday 16 November 2011 03:51:01 pm Timothy Pearson wrote:
I would definitely encourage the usage of an open format flat file (or files), such as fodt or some sort of Latex format, in the GIT repository. This would greatly simplify differences between versions (if needed), and thereby make it easier for those without write access to GIT to jump in, edit the document, and submit a patch with their additions.
Not everybody will have a Latex editor at the ready. I don't know what fodt is. Most people will have an ODT-compatible editor such as LibreOffice or AbiWord (I think even MS Office can read/save ODT files since their 2007 edition).
Excuse me if I jump in the discussion just to put my 2 cents about the editor. What about the good old LyX?
It's easy to use, it outputs LaTeX, it's multi-platform and it's Free Software.
Andrea
Excuse me if I jump in the discussion just to put my 2 cents about the editor. What about the good old LyX?
It's easy to use, it outputs LaTeX, it's multi-platform and it's Free Software.
Lyx is a front-end wrapper to LaTeX. Basically then we're back to discussing markup. :) Lyx could be an option for some documentation teams, but the internal team still needs to learn LaTex. Doable if those involved have the time for that kind of thing. :)
Much of our recent discussion has been how to encourage non team members to contribute where nothing more than everyday word processor skills are expected.
For internal purposes the leading focus is using a format that is maintainable in GIT for merging collaborative changes in a team environment. Hence the arguments in favor of markup, which is text based. I think we have agreed to ODT, which fundamentally is XML, which is text based.
ODT allows writers to use any software supporting that format and does not limit contributors to a specific tool chain.
Darrell
On 17 November 2011 12:47, Darrell Anderson humanreadable@yahoo.com wrote:
Excuse me if I jump in the discussion just to put my 2 cents about the editor. What about the good old LyX?
It's easy to use, it outputs LaTeX, it's multi-platform and it's Free Software.
Lyx is a front-end wrapper to LaTeX. Basically then we're back to discussing markup. :) Lyx could be an option for some documentation teams, but the internal team still needs to learn LaTex. Doable if those involved have the time for that kind of thing. :)
Much of our recent discussion has been how to encourage non team members to contribute where nothing more than everyday word processor skills are expected.
For internal purposes the leading focus is using a format that is maintainable in GIT for merging collaborative changes in a team environment. Hence the arguments in favor of markup, which is text based. I think we have agreed to ODT, which fundamentally is XML, which is text based.
ODT allows writers to use any software supporting that format and does not limit contributors to a specific tool chain.
Darrell
Actually I am almost certain only LibreOffice and the now dead OpenOffice can import and work in fodt. Odt support is pretty standard
Can someone shed light on this?
On Thursday 17 November 2011 12:56:56 pm Calvin Morrison wrote:
On 17 November 2011 12:47, Darrell Anderson humanreadable@yahoo.com wrote:
Excuse me if I jump in the discussion just to put my 2 cents about the editor. What about the good old LyX?
It's easy to use, it outputs LaTeX, it's multi-platform and it's Free Software.
Lyx is a front-end wrapper to LaTeX. Basically then we're back to discussing markup. :) Lyx could be an option for some documentation teams, but the internal team still needs to learn LaTex. Doable if those involved have the time for that kind of thing. :)
Much of our recent discussion has been how to encourage non team members to contribute where nothing more than everyday word processor skills are expected.
For internal purposes the leading focus is using a format that is maintainable in GIT for merging collaborative changes in a team environment. Hence the arguments in favor of markup, which is text based. I think we have agreed to ODT, which fundamentally is XML, which is text based.
ODT allows writers to use any software supporting that format and does not limit contributors to a specific tool chain.
Darrell
Actually I am almost certain only LibreOffice and the now dead OpenOffice can import and work in fodt. Odt support is pretty standard
Can someone shed light on this?
I can't speak toward FODT since I don't use it. I think we should just use plain ODT.
If we use FODT, most distros will include OpenOffice/LibreOffice by default. It includes a familiar interface closely resembling most other office apps (except MS Office 2007+, but older version still resemble OOo/LO).
OOo and LO both have Windows/Mac version, some Win/Mac users use it. Not all people will want to install it, hence my argument in favor of plain ODT, which is supported by MS Office 2007 and (it now seems) most other office apps.
On Thursday 17 November 2011 12:56:56 pm Calvin Morrison wrote:
On 17 November 2011 12:47, Darrell Anderson humanreadable@yahoo.com wrote:
Excuse me if I jump in the discussion just to put my 2 cents about the editor. What about the good old LyX?
It's easy to use, it outputs LaTeX, it's multi-platform and it's Free Software.
Lyx is a front-end wrapper to LaTeX. Basically then we're back to discussing markup. :) Lyx could be an option for some documentation teams, but the internal team still needs to learn LaTex. Doable if
those
involved have the time for that kind of thing. :)
Much of our recent discussion has been how to encourage non team
members
to contribute where nothing more than everyday word processor skills
are
expected.
For internal purposes the leading focus is using a format that is maintainable in GIT for merging collaborative changes in a team environment. Hence the arguments in favor of markup, which is text
based.
I think we have agreed to ODT, which fundamentally is XML, which is
text
based.
ODT allows writers to use any software supporting that format and does not limit contributors to a specific tool chain.
Darrell
Actually I am almost certain only LibreOffice and the now dead OpenOffice can import and work in fodt. Odt support is pretty standard
Can someone shed light on this?
I can't speak toward FODT since I don't use it. I think we should just use plain ODT.
If we use FODT, most distros will include OpenOffice/LibreOffice by default. It includes a familiar interface closely resembling most other office apps (except MS Office 2007+, but older version still resemble OOo/LO).
OOo and LO both have Windows/Mac version, some Win/Mac users use it. Not all people will want to install it, hence my argument in favor of plain ODT, which is supported by MS Office 2007 and (it now seems) most other office apps.
The biggest issue here is that ODT files are compressed binary blobs, and therefore work rather terribly in version control systems. Maybe it would work better to automatically create a "HEAD" ODT file from the FODT in the GIT repository that anyone can download/edit, and when it comes time to merge their changes we can open the .odt and export as .fodt prior to commit.
Tim
On Thursday 17 November 2011 01:09:34 pm Timothy Pearson wrote:
The biggest issue here is that ODT files are compressed binary blobs, and therefore work rather terribly in version control systems. Maybe it would work better to automatically create a "HEAD" ODT file from the FODT in the GIT repository that anyone can download/edit, and when it comes time to merge their changes we can open the .odt and export as .fodt prior to commit.
Possible through a shell script? Would make things easier.
On 17 November 2011 13:23, Kristopher John Gamrat chaotickjg@gmail.comwrote:
On Thursday 17 November 2011 01:09:34 pm Timothy Pearson wrote:
The biggest issue here is that ODT files are compressed binary blobs, and therefore work rather terribly in version control systems. Maybe it
would
work better to automatically create a "HEAD" ODT file from the FODT in
the
GIT repository that anyone can download/edit, and when it comes time to merge their changes we can open the .odt and export as .fodt prior to commit.
Possible through a shell script? Would make things easier.
Actually I assume it would be done through a git post-commit hook and a script to generate the odt
Calvin
On Thursday 17 November 2011 01:09:34 pm Timothy Pearson wrote:
The biggest issue here is that ODT files are compressed binary blobs, and therefore work rather terribly in version control systems. Maybe it would work better to automatically create a "HEAD" ODT file from the FODT in the GIT repository that anyone can download/edit, and when it comes time to merge their changes we can open the .odt and export as .fodt prior to commit.
Possible through a shell script? Would make things easier.
Should be. Most LibreOffice functions can be automated.
Tim
On Thursday 17 November 2011 19:23:24 Kristopher John Gamrat wrote:
On Thursday 17 November 2011 01:09:34 pm Timothy Pearson wrote:
The biggest issue here is that ODT files are compressed binary blobs, and therefore work rather terribly in version control systems. Maybe it would work better to automatically create a "HEAD" ODT file from the FODT in the GIT repository that anyone can download/edit, and when it comes time to merge their changes we can open the .odt and export as .fodt prior to commit.
Possible through a shell script? Would make things easier.
I have something like that for converting documents to pdf, a macro invoked by a script shell. Should be easy to adapt.
On Wed, Nov 16, 2011 at 15:51, Timothy Pearson kb9vqf@pearsoncomputing.net wrote:
I would definitely encourage the usage of an open format flat file (or files), such as fodt or some sort of Latex format, in the GIT repository. This would greatly simplify differences between versions (if needed), and thereby make it easier for those without write access to GIT to jump in, edit the document, and submit a patch with their additions.
And I would really like to see this idea take off for R14.0! This is one area where we can really shine compared to other desktops out there.
Tim
May I suggest then https://github.com/github/gollum?
If you're interested in collecting old guides to supplement your information, the Gentoo KDE3 configuration guide can be scrounged from the Wayback Machine:
http://web.archive.org/web/20060630093822/http://www.gentoo.org/doc/en/kde-c...
The license is Creative Commons Attribution/Share Alike. Much of the guide is taken up with Gentoo-specific package manager commands, but there are a few bits and pieces that may be good for something.
-
Andrea Cascio -
Calvin Morrison -
Darrell Anderson -
E. Liddell -
Keith Daniels -
Kristopher John Gamrat -
Robert Xu -
Timothy Pearson