Thread: [Audacity-devel] Documentation updates
A free multi-track audio editor and recorder
Brought to you by:
aosiniao
Menu
▾
▴
audacity-devel
|
From: Richard A. <ri...@au...> - 2005-08-25 19:04:59
Attachments:
audacity_manual_update3.diff
|
Three items in response to some user feedback: 1)The latest manual update patch, clarifies the compression of AU files. (attached). Current new version is at http://www-users.york.ac.uk/~raa110/audacity/audacity-manual-1.2.3-r2.zip (sorry dave, keep doing things to this. My current revision will always be at http://www-users.york.ac.uk/~raa110/audacity/audacity-manual-1.2.zip) 2)A new version of the quick reference (single page version), available at http://www-users.york.ac.uk/~raa110/audacity/reference.html 3)A better way to do the PDF version that doesn't involve hacking the valid XHTML about by hand. All the required files and the bash script to do it are in: http://www-users.york.ac.uk/~raa110/audacity/audacity-reference-1.2.3.tar.bz2 The output is: http://www-users.york.ac.uk/~raa110/audacity/audacity-reference-1.2.3.pdf Richard |
|
From: Richard A. <ri...@au...> - 2005-08-26 19:24:46
Attachments:
audacity-manual-update4.diff.gz
|
On Thu, 2005-08-25 at 19:54 +0100, Richard Ash wrote: > Three items in response to some user feedback: I promise I will stop doing things to the manual soon! Latest patch is all cosmetic, fixes a lot of page titles and the like that became very obvious when trying to convert to PDF. New version online at http://www-users.york.ac.uk/~raa110/audacity/audacity-manual-1.2.3-r3.zip On the subject of PDFs, there is a PDF version of the latest manual release available at: http://www-users.york.ac.uk/~raa110/audacity/audacity-manual-1.2.pdf It has a lot of layout bugs (because htmldoc doesn't know about CSS), and looks pretty basic, but it does at least work. The htmldoc file that creates this from the zip file is: http://www-users.york.ac.uk/~raa110/audacity/audacity-manual-1.2.book Currently there aren't any bodges to make this work, I may write a bash script when there are some, unless htmldoc gets fixed to take XHTML 1.1 / CSS first. Just put it the level of the audacity-manual-1.2 directory and do $ htmldoc --batch audacity-manual-1.2.book This will spit out three errors that I haven't currently got the patience to fix. Richard |
|
From: Richard A. <ri...@au...> - 2005-09-20 21:31:29
|
I've just tried to put some updates into the built-in help for audacity, and discovered that my CVS binary is loading the system installed audacity 1.2.3 help file not the local 1.2.4 file I just built! Any ideas why or how to stop it? Also, anyone know what in the way of html it can cope with (XHTML? CSS?). I'm hoping to put all the changes in my one-page reference http://www-users.york.ac.uk/~raa110/audacity/1.2.4/audacity-reference-1.2.4.tar.bz2 into the multi page built-in help, and maybe do a script to convert the multi page to single page to save maintaining both. Richard |
|
From: Dominic M. <do...@au...> - 2005-09-21 07:24:50
|
On Sep 20, 2005, at 2:31 PM, Richard Ash wrote:
> I've just tried to put some updates into the built-in help for
> audacity,
> and discovered that my CVS binary is loading the system installed
> audacity 1.2.3 help file not the local 1.2.4 file I just built! Any
> ideas why or how to stop it?
The logic (in Help.cpp) to look for audacity-1.2-help.htb is:
1. Search in the path list (AudacityApp.cpp::OnInit)
On Windows, it uses argv[0] to figure out the path to the
currently running executable, and looks for the help file in
that same directory.
2. If not there, look for the config variable "/Help/HelpFilePath1.2"
(On Windows, set it with RegEdit).
3. If that doesn't exist, or still not found, prompt the user
> Also, anyone know what in the way of html it can cope with (XHTML?
> CSS?). I'm hoping to put all the changes in my one-page reference
> http://www-users.york.ac.uk/~raa110/audacity/1.2.4/audacity-
> reference-1.2.4.tar.bz2
> into the multi page built-in help, and maybe do a script to convert
> the
> multi page to single page to save maintaining both.
See "tags supported by wxHTML" here:
http://www.wxwidgets.org/manuals/2.4.2/wx499.htm
- Dominic
> Richard
>
>
>
> -------------------------------------------------------
> SF.Net email is sponsored by:
> Tame your development challenges with Apache's Geronimo App Server.
> Download it for free - -and be entered to win a 42" plasma tv or
> your very
> own Sony(tm)PSP. Click here to play: http://sourceforge.net/
> geronimo.php
> _______________________________________________
> Audacity-devel mailing list
> Aud...@li...
> https://lists.sourceforge.net/lists/listinfo/audacity-devel
>
|
|
From: Richard A. <ri...@au...> - 2005-09-21 20:33:09
|
Discovered that you can load the uncompressed index file (audacity.hhp) with the python helpviewer, which solves the immediate problem, and saves zipping the help up. > > Also, anyone know what in the way of html it can cope with (XHTML? > > CSS?). I'm hoping to put all the changes in my one-page reference > > http://www-users.york.ac.uk/~raa110/audacity/1.2.4/audacity-reference-1.2.4.tar.bz2 > > into the multi page built-in help, and maybe do a script to convert > > the multi page to single page to save maintaining both. > > See "tags supported by wxHTML" here: > > http://www.wxwidgets.org/manuals/2.4.2/wx499.htm Ah. No CSS, and various other issues like no UTF-8 charset tags and inline styles don't work. Looks like quite a lot of work to get from one to the other (starting with every centered object ...). At least comments work. Short of creating a custom converter to get from one to the other, or maintaining two completely different documents, does anyone have any suggestions? Richard |
|
From: Dominic M. <do...@au...> - 2005-09-21 22:30:03
|
Richard Ash wrote: > Short of creating a custom converter to get from one to the other, or > maintaining two completely different documents, does anyone have any > suggestions? More long-term, I think we should consider something along the lines of documentation in LaTeX and latex2html to generate the documentation. I'm neutral on whether we use LaTeX or not, but we should look around for the best package that turns text-based structured markup into the three forms we want with maximum flexibility: 1. Very simply HTML (for embedding in the program) 2. Modern XHTML with CSS (for the website) 3. PDF (for printing) - Dominic |
|
From: Dominic M. <do...@au...> - 2005-09-21 23:10:57
|
Richard Ash wrote: > Short of creating a custom converter to get from one to the other, or > maintaining two completely different documents, does anyone have any > suggestions? We should look into DocBook. It's a relatively simple XML format for describing technical documentation, with a whole suite of converters for turning it into MSHelp (which is exactly what wxHTML is), full HTML, PDF, and more: http://www.docbook.org/ http://wiki.docbook.org/topic/formats http://www.xml-dev.com/blog/test.php http://docbook.sourceforge.net/ http://en.wikipedia.org/wiki/DocBook We could write a one-time converter to convert what we have into DocBook, fixing things by hand, and from then on we'd have an open, well-supported, and flexible system for generating documentation in all forms. - Dominic |
|
From: Alexandre P. <ale...@gm...> - 2005-09-22 12:44:23
|
On 9/22/05, Dominic Mazzoni <do...@au...> wrote: > Richard Ash wrote: > > Short of creating a custom converter to get from one to the other, or > > maintaining two completely different documents, does anyone have any > > suggestions? > > We should look into DocBook. It's a relatively simple XML format for > describing technical documentation, with a whole suite of converters for > turning it into MSHelp (which is exactly what wxHTML is), full HTML, > PDF, and more: > > http://www.docbook.org/ > http://wiki.docbook.org/topic/formats > http://www.xml-dev.com/blog/test.php > http://docbook.sourceforge.net/ > http://en.wikipedia.org/wiki/DocBook > > We could write a one-time converter to convert what we have into > DocBook, fixing things by hand, and from then on we'd have an open, > well-supported, and flexible system for generating documentation in all > forms. Okay, 3 eurocents from a docbook zealot (obviously, me :)) 1. "relatively simple XML format". DocBook/XML is considered as difficult by many technical writers. Due to XML nature of this format no company in the market has succeded in creating one good usable XML editor (in WYSIWYM style), though there are tens of them. And not so many people have fun editing it in text editors with syntax highlight. This is one of the reasons DocBook is not accepted as widely as it could be yet. 2. You can't create complete HTML Help file (.chm). Htmlhelp styles from Norman Walsh create a project file for HTML Help Workshop only. Workshop is freely downloadable though. 2. "One-time converter" is a good joke :) Basically it means regexp magic like 's/p/para/n', followed by more complicated substitution like "<h1>some text</h1>" to "<section><title>Some text</title></section>". I even used to write one myself in the early days of my work at ALT Linux. Someone will have a good time fixing unclosed tags and structure of dicuments. Actually, I could volunteer for this. My 1,5 year old book on Audacity is available in DocBook/XML, btw. Alexandre |
|
From: Markus M. <me...@me...> - 2005-09-22 13:48:43
|
Dominic Mazzoni schrieb: > We should look into DocBook. It's a relatively simple XML format for > describing technical documentation, with a whole suite of converters > for turning it into MSHelp (which is exactly what wxHTML is), full > HTML, PDF, and more: A system which can export simple HTML and Postscript can be found here: http://www.ribbonsoft.com/manstyle.html While not as feature-rich as DocBook, it took me about 5 minutes to learn it (and I still haven't figured out how to use DocBook ;-). Of course I am not a documentation writer, so I think the documentation writers should figure out what to use themselves (after all they are the ones that have to use it). On the other hand, if one wants to use DocBook, it may be possible, that an experienced DocBook user (Alexandre?) provides a kind of skeleton. Other doc writers would then just have to insert text and some simple markup in the appropriate places, without thinking about the "big picture". Markus |
|
From: Alexandre P. <ale...@gm...> - 2005-09-22 14:08:46
|
On 9/22/05, Markus Meyer <me...@me...> wrote: > Dominic Mazzoni schrieb: > > > We should look into DocBook. It's a relatively simple XML format for > > describing technical documentation, with a whole suite of converters > > for turning it into MSHelp (which is exactly what wxHTML is), full > > HTML, PDF, and more: > > > A system which can export simple HTML and Postscript can be found here: > > http://www.ribbonsoft.com/manstyle.html > > While not as feature-rich as DocBook, it took me about 5 minutes to > learn it (and I still haven't figured out how to use DocBook ;-). Well, sample.xml doesn't look much different > ones that have to use it). On the other hand, if one wants to use > DocBook, it may be possible, that an experienced DocBook user > (Alexandre?) provides a kind of skeleton. Other doc writers would then > just have to insert text and some simple markup in the appropriate > places, without thinking about the "big picture". Let me share my experience. The very first docs we produced in ALT Linux were authored in OpenOffice.org Writer. We had 5 authors and 3 contributive editors at that time. It was absolutely insane to keep using Writer for collaborative work, so we considered moving to DocBook/XML + CVS for its modularity (once you learn XInclude, you can't live without it :)). To our disappointment many potential contributors couldn't jump into DocBook/XML wagon, because there were no tutorials for beginners in Russian and markup seemed to be too complex for them. The guy who came too do my job after I quit, tried to invent some simple text format and he seems to have failed so far. About half a year ago a wiki was set up at freesource.info for ALT Linux contributors and it looks like people are accepting this way of documenting software, because a) markup language is easy; b) result can be seen just by clicking "Preview" button. Some wiki engines even provide export to PDF/DOC/etc. So, in ideal case I would rather vote for some wiki with HTML/PDF export. If you are keen of this idea, I can do an investigation in this area for you. Alexandre |
|
From: Anthony A. O. <ai...@gm...> - 2005-09-23 13:18:20
|
On Thu, 22 Sep 2005 18:08:27 +0400, Alexandre Prokoudine wrote: ... >About half a year ago a wiki was set up at freesource.info for ALT >Linux contributors and it looks like people are accepting this way of >documenting software, because > >a) markup language is easy; >b) result can be seen just by clicking "Preview" button. > >Some wiki engines even provide export to PDF/DOC/etc. So, in ideal >case I would rather vote for some wiki with HTML/PDF export. If you >are keen of this idea, I can do an investigation in this area for you. Neat. Even I could contribute something meaningful in my spare time that way. Documentation AND design ideas. Tony |
|
From: Rupert S. <rup...@li...> - 2005-09-22 13:29:37
Attachments:
signature.asc
|
Dominic Mazzoni wrote: > Richard Ash wrote: > >> Short of creating a custom converter to get from one to the other, or >> maintaining two completely different documents, does anyone have any >> suggestions? > > > We should look into DocBook. It's a relatively simple XML format for > describing technical documentation, with a whole suite of converters for > turning it into MSHelp (which is exactly what wxHTML is), full HTML, > PDF, and more: > > http://www.docbook.org/ > http://wiki.docbook.org/topic/formats > http://www.xml-dev.com/blog/test.php > http://docbook.sourceforge.net/ > http://en.wikipedia.org/wiki/DocBook > > We could write a one-time converter to convert what we have into > DocBook, fixing things by hand, and from then on we'd have an open, > well-supported, and flexible system for generating documentation in all > forms. > > - Dominic > I think that docbook is a fantastic idea; the only problem is that the standard HTML it outputs isn't hugely pretty (although would probably work for the help HTML engine). My suggestion would be to use docbook to give you a standard HTML version, which you could customise slightly, aiming for the help engine. After this, you could use XSLT at build time and/or CSS at viewtime for the XHTML swanky version. Docbook can do pdf for you nicely, so a customised pdf output would be fine. To clarify, what I mean by customised is that you've got to give docbook some style info to stop it looking like the standard pages you get at gnu.org - helpful, but not nice. I'm not entirely sure whether this is done by CSS afterwards, in which case we would have a problem with the base HTML version, or by something internally in docbook, which would be good news. I'd be very happy to give a hand by converting the originals to docbook - I reckon for a one-off like that, emacs keyboard macros are the way to go! :) Rupert |
|
From: Alexandre P. <ale...@gm...> - 2005-09-22 13:42:14
|
On 9/22/05, Rupert Swarbrick <rup...@li...> wrote: > Docbook can do pdf for you nicely, so a customised pdf output would be fi= ne. There is only one tool for producing nice PDFs in any language without any glitches whatsoever. It's proprietary XEP. All other tools (PassiveTeX, db2latex, FOP) require extra attention. > To clarify, what I mean by customised is that you've got to give docbook > some style info to stop it looking like the standard pages you get at > gnu.org - helpful, but not nice. I'm not entirely sure whether this is > done by CSS afterwards, in which case we would have a problem with the > base HTML version, or by something internally in docbook, which would be > good news. You can merge CSS directly into HTML code by output or keep it separately. Alexandre |
|
From: Dominic M. <do...@au...> - 2005-09-22 21:40:04
|
On Sep 22, 2005, at 7:08 AM, Alexandre Prokoudine wrote: > About half a year ago a wiki was set up at freesource.info for ALT > Linux contributors and it looks like people are accepting this way of > documenting software, because > > a) markup language is easy; > b) result can be seen just by clicking "Preview" button. > > Some wiki engines even provide export to PDF/DOC/etc. So, in ideal > case I would rather vote for some wiki with HTML/PDF export. If you > are keen of this idea, I can do an investigation in this area for you. Actually I like the idea of a Wiki for the documentation - the catch being that it wouldn't be open to the general public, but rather just to a smaller set of contributors. Here's a page on PDF export from MediaWiki: http://meta.wikimedia.org/wiki/PDF_Export It apparently uses htmldoc. - Dominic |
|
From: Alexandre P. <ale...@gm...> - 2005-09-25 22:54:02
|
On 9/23/05, Dominic Mazzoni <do...@au...> wrote: > Here's a page on PDF export from MediaWiki: > > http://meta.wikimedia.org/wiki/PDF_Export > > It apparently uses htmldoc. On the other hand Instiki has both PDF and zipped HTML export. Alexandre |
|
From: Alexandre P. <ale...@gm...> - 2005-09-27 23:00:51
|
So, what are you up to, guys? ;) Alexandre On 9/26/05, Alexandre Prokoudine <ale...@gm...> wrote: > On 9/23/05, Dominic Mazzoni <do...@au...> wrote: > > > Here's a page on PDF export from MediaWiki: > > > > http://meta.wikimedia.org/wiki/PDF_Export > > > > It apparently uses htmldoc. > > On the other hand Instiki has both PDF and zipped HTML export. > > Alexandre > |
×
Want the latest updates on software, tech news, and AI?
Get latest updates about software, tech news, and AI from SourceForge directly in your inbox once a month.
Thanks for helping keep SourceForge clean.
X