Re: Calling for Server Guide reviewers/contributors - - TRUSTY
On Mon, May 16, 2016 at 4:54 PM, Doug Smythies wrote: > On 2016.01.03 7:58 Peter Matulis wrote: > > On 01/03/2014 10:43 AM, Peter Matulis wrote: > >> On 01/03/2014 01:08 AM, Mauricio Tavares wrote: > > [...] > > Don't forget to install Sphinx. > > $ sudo apt-get install sphinx-doc > > Into my main 16.04 test server, the one on which I compile Ubuntu docs, I > installed "sphinx-doc", but an HTML compile attempt still error exits with: > > doug@s15:~/sguide-peter/p$ make html > sphinx-build -b html -d _build/doctrees . _build/html > make: sphinx-build: Command not found > Makefile:45: recipe for target 'html' failed > make: *** [html] Error 127 > > I could confirm the issue, but the following gets it working for me $ sudo apt-get install python3-sphinx -- ubuntu-server mailing list ubuntu-server@lists.ubuntu.com https://lists.ubuntu.com/mailman/listinfo/ubuntu-server More info: https://wiki.ubuntu.com/ServerTeam
RE: Calling for Server Guide reviewers/contributors - - TRUSTY
On 2016.01.03 7:58 Peter Matulis wrote: > On 01/03/2014 10:43 AM, Peter Matulis wrote: >> On 01/03/2014 01:08 AM, Mauricio Tavares wrote: >>> I can help; it would be a good way to understand the new format. >>> Should I do what you did and fetch a chapter somehow, edit it and >>> place it somewhere so it can be seen before brought back? >> >> Let's work from here: >> >> https://code.launchpad.net/~petermatulis/+junk/serverguide-rst >> >> You can make a branch of that and then I can occasionally merge in your >> new work. > > Mauricio, and anyone else, start by looking at installation.rst. It > contains good samples of the new way of doing things. For the > cross-reference link to the 'Aptitude' heading you will also need to > look at package-management.rst. Hi Peter, We just did an update publish of the 16.04 serverguide on help.ubuntu.com. To me it seems like a good time to look deeper into a possible markdown language change. I wanted to build the Ubuntu Serverguide from your markdown test project and compare. Could you update it from the DocBook master source? I didn't see a "PDF" option in the Makefile. Is there a way to compile the PDF version of the Serverguide? Perhaps I should use "latexpdf"? > Don't forget to install Sphinx. > $ sudo apt-get install sphinx-doc Into my main 16.04 test server, the one on which I compile Ubuntu docs, I installed "sphinx-doc", but an HTML compile attempt still error exits with: doug@s15:~/sguide-peter/p$ make html sphinx-build -b html -d _build/doctrees . _build/html make: sphinx-build: Command not found Makefile:45: recipe for target 'html' failed make: *** [html] Error 127 Linux s15 4.4.0-21-generic #37-Ubuntu SMP Mon Apr 18 18:33:37 UTC 2016 x86_64 x86_64 x86_64 GNU/Linux doug@s15:~/sguide-trunk/x/build$ dpkg -l | grep sph ii libjs-sphinxdoc 1.3.6-2ubuntu1 JavaScript support for Sphinx documentation ii sphinx-doc 1.3.6-2ubuntu1 documentation generator for Python projects - documentation ... Doug -- ubuntu-server mailing list ubuntu-server@lists.ubuntu.com https://lists.ubuntu.com/mailman/listinfo/ubuntu-server More info: https://wiki.ubuntu.com/ServerTeam
Re: Calling for Server Guide reviewers/contributors - - TRUSTY
Quoting Doug Smythies (dsmyth...@telus.net): > > On 2014.02.06 15:05 Serge Hallyn wrote: > > Quoting Peter Matulis (peter.matu...@canonical.com): > >> On 01/03/2014 01:08 AM, Mauricio Tavares wrote: > >>> On Fri, Jan 3, 2014 at 5:58 AM, Peter Matulis > >> > After having spent a good part of the day going through just one file > (chapter) I now know how much work is involved: > > 1. A good number of external links are broken > 2. All internal links are broken and require a new way of linking > (source and destination) > 3. All admonitions (i.e. "notes" and "warnings") are crippled, but not > outright broken > 4. All working external links *should* be changed to a new format > 5. Heading organization need to be redone in all chapters. All > chapters > have multiple 1st level headings. This is what was causing the > flattened/expansize table of contents I mentioned earlier. > 6. More theme/customization work > 7. Research how this conversion will affect the translators and come up > with a corrective plan > > I can't do all this myself; I estimate there is about 120 hours of work > required. Anyone? > > >>> I can help; it would be a good way to understand the new format. > >>> Should I do what you did and fetch a chapter somehow, edit it and > >>> place it somewhere so it can be seen before brought back? > >> > >> Let's work from here: > >> > >> https://code.launchpad.net/~petermatulis/+junk/serverguide-rst > >> > >> You can make a branch of that and then I can occasionally merge in your > >> new work. > > > Oh, drat, I was starting from lp:serverguide (with small update pushed > > to lp:~serge-hallyn/serverguide/lxc-trusty-update) > > > I'll take a look at your tree. (The lxc update will need to be > > extensive) > > Serge: Please continue your work with lp:serverguide as the master code. > > There is no way there will be a change over before the serverguide 14.04 > is released. > > This thread stalled out when trying to estimate the translations > portion of the project (at least that is my understanding). > > Please consider to put your name under Chapter 20.4 on: > > https://wiki.ubuntu.com/DocumentationTeam/SystemDocumentation/UbuntuServerGu > ide > > the serverguide task list, as reviewing it. > > The serverguide doc team is very grateful for your help. Ok, thanks for the info. FWIW I intend to cut quite a bit out of the section (as well as add information on new features) in order to make it more readable, more maintainable, and less redundant (i.e. refer to the manpages rather than list detailed lxc.conf info) So it's going to be more of a re-write than a review. -serge -- ubuntu-server mailing list ubuntu-server@lists.ubuntu.com https://lists.ubuntu.com/mailman/listinfo/ubuntu-server More info: https://wiki.ubuntu.com/ServerTeam
RE: Calling for Server Guide reviewers/contributors - - TRUSTY
On 2014.02.06 15:05 Serge Hallyn wrote: > Quoting Peter Matulis (peter.matu...@canonical.com): >> On 01/03/2014 01:08 AM, Mauricio Tavares wrote: >>> On Fri, Jan 3, 2014 at 5:58 AM, Peter Matulis >> After having spent a good part of the day going through just one file (chapter) I now know how much work is involved: 1. A good number of external links are broken 2. All internal links are broken and require a new way of linking (source and destination) 3. All admonitions (i.e. "notes" and "warnings") are crippled, but not outright broken 4. All working external links *should* be changed to a new format 5. Heading organization need to be redone in all chapters. All chapters have multiple 1st level headings. This is what was causing the flattened/expansize table of contents I mentioned earlier. 6. More theme/customization work 7. Research how this conversion will affect the translators and come up with a corrective plan I can't do all this myself; I estimate there is about 120 hours of work required. Anyone? >>> I can help; it would be a good way to understand the new format. >>> Should I do what you did and fetch a chapter somehow, edit it and >>> place it somewhere so it can be seen before brought back? >> >> Let's work from here: >> >> https://code.launchpad.net/~petermatulis/+junk/serverguide-rst >> >> You can make a branch of that and then I can occasionally merge in your >> new work. > Oh, drat, I was starting from lp:serverguide (with small update pushed > to lp:~serge-hallyn/serverguide/lxc-trusty-update) > I'll take a look at your tree. (The lxc update will need to be > extensive) Serge: Please continue your work with lp:serverguide as the master code. There is no way there will be a change over before the serverguide 14.04 is released. This thread stalled out when trying to estimate the translations portion of the project (at least that is my understanding). Please consider to put your name under Chapter 20.4 on: https://wiki.ubuntu.com/DocumentationTeam/SystemDocumentation/UbuntuServerGu ide the serverguide task list, as reviewing it. The serverguide doc team is very grateful for your help. -- ubuntu-server mailing list ubuntu-server@lists.ubuntu.com https://lists.ubuntu.com/mailman/listinfo/ubuntu-server More info: https://wiki.ubuntu.com/ServerTeam
Re: Calling for Server Guide reviewers/contributors - - TRUSTY
Quoting Peter Matulis (peter.matu...@canonical.com): > On 01/03/2014 01:08 AM, Mauricio Tavares wrote: > > On Fri, Jan 3, 2014 at 5:58 AM, Peter Matulis > > >> After having spent a good part of the day going through just one file > >> (chapter) I now know how much work is involved: > >> > >> 1. A good number of external links are broken > >> 2. All internal links are broken and require a new way of linking > >> (source and destination) > >> 3. All admonitions (i.e. "notes" and "warnings") are crippled, but not > >> outright broken > >> 4. All working external links *should* be changed to a new format > >> 5. Heading organization need to be redone in all chapters. All chapters > >> have multiple 1st level headings. This is what was causing the > >> flattened/expansize table of contents I mentioned earlier. > >> 6. More theme/customization work > >> 7. Research how this conversion will affect the translators and come up > >> with a corrective plan > >> > >> I can't do all this myself; I estimate there is about 120 hours of work > >> required. Anyone? > >> > > I can help; it would be a good way to understand the new format. > > Should I do what you did and fetch a chapter somehow, edit it and > > place it somewhere so it can be seen before brought back? > > Let's work from here: > > https://code.launchpad.net/~petermatulis/+junk/serverguide-rst > > You can make a branch of that and then I can occasionally merge in your > new work. Oh, drat, I was starting from lp:serverguide (with small update pushed to lp:~serge-hallyn/serverguide/lxc-trusty-update) I'll take a look at your tree. (The lxc update will need to be extensive) -- ubuntu-server mailing list ubuntu-server@lists.ubuntu.com https://lists.ubuntu.com/mailman/listinfo/ubuntu-server More info: https://wiki.ubuntu.com/ServerTeam
Re: Calling for Server Guide reviewers/contributors - - TRUSTY
On Wed, Jan 8, 2014 at 3:25 PM, Elizabeth Krumbach Joseph wrote: > On Tue, Jan 7, 2014 at 6:09 AM, Peter Matulis > wrote: >> On 01/03/2014 01:18 PM, Elizabeth Krumbach Joseph wrote: >>> On Fri, Jan 3, 2014 at 9:37 AM, Doug Smythies wrote: However, I think item 7, translations and the overall workflow is the unknown at this time, and could be a major hurtle or even a show stopper. We need to estimate that part of the project for feasibility, person hours, and potential timeline for implementation. Myself, I would put a hold on items 1-6 for now. Myself, I do not know how to even start looking into item 7, but I'll help if possible. >>> >>> Huge +1 here. This is an LTS release and I'm not sure this is the best >>> time to take upon this major overhaul given the amount of time >>> involved and the uncertainty about translations. Translations are very >>> important, particularly in an LTS, and we do a great disservice to our >>> translations volunteers if we do this without a plan for them, or >>> otherwise abruptly change things for them. How ever we do this, it's >>> likely that all strings will be shown as modified and they'll have to >>> begin translations from scratch rather than just updating changed >>> strings. >>> >>> I'd feel much better doing this for 14.10, when it's a bit less >>> important to have a solid, translated documentation for release. >> >> As we know, there is a chorus that goes up at every UDS that says we >> should change away from XML but no one ever did anything. I decided to >> push forward with this in order to i) see what would be involved and ii) >> provoke reactions from people. From what I can see I've achieved both >> goals. >> >> It would be great if a knowledgeable person from Translations could get >> in contact with me about the impact this transition would have for them. > > Your best bet is probably the translators mailing list: > ubuntu-translat...@lists.ubuntu.com Oops, this is already on the translators list, the translator *coordinators* may be the ones to talk to: https://launchpad.net/~ubuntu-translations-coordinators -- Elizabeth Krumbach Joseph || Lyz || pleia2 http://www.princessleia.com -- ubuntu-server mailing list ubuntu-server@lists.ubuntu.com https://lists.ubuntu.com/mailman/listinfo/ubuntu-server More info: https://wiki.ubuntu.com/ServerTeam
Re: Calling for Server Guide reviewers/contributors - - TRUSTY
On Tue, Jan 7, 2014 at 6:09 AM, Peter Matulis wrote: > On 01/03/2014 01:18 PM, Elizabeth Krumbach Joseph wrote: >> On Fri, Jan 3, 2014 at 9:37 AM, Doug Smythies wrote: >>> However, I think item 7, translations and the overall workflow is >>> the unknown at this time, and could be a major hurtle or even a >>> show stopper. We need to estimate that part of the project for >>> feasibility, person hours, and potential timeline for implementation. >>> Myself, I would put a hold on items 1-6 for now. >>> Myself, I do not know how to even start looking into item 7, but >>> I'll help if possible. >> >> Huge +1 here. This is an LTS release and I'm not sure this is the best >> time to take upon this major overhaul given the amount of time >> involved and the uncertainty about translations. Translations are very >> important, particularly in an LTS, and we do a great disservice to our >> translations volunteers if we do this without a plan for them, or >> otherwise abruptly change things for them. How ever we do this, it's >> likely that all strings will be shown as modified and they'll have to >> begin translations from scratch rather than just updating changed >> strings. >> >> I'd feel much better doing this for 14.10, when it's a bit less >> important to have a solid, translated documentation for release. > > As we know, there is a chorus that goes up at every UDS that says we > should change away from XML but no one ever did anything. I decided to > push forward with this in order to i) see what would be involved and ii) > provoke reactions from people. From what I can see I've achieved both > goals. > > It would be great if a knowledgeable person from Translations could get > in contact with me about the impact this transition would have for them. Your best bet is probably the translators mailing list: ubuntu-translat...@lists.ubuntu.com I've also included David Planella in the Cc: to see if he can give some feedback (he's worked with the translations teams for several years). -- Elizabeth Krumbach Joseph || Lyz || pleia2 http://www.princessleia.com -- ubuntu-server mailing list ubuntu-server@lists.ubuntu.com https://lists.ubuntu.com/mailman/listinfo/ubuntu-server More info: https://wiki.ubuntu.com/ServerTeam
Re: Calling for Server Guide reviewers/contributors - - TRUSTY
On 01/03/2014 01:18 PM, Elizabeth Krumbach Joseph wrote: > On Fri, Jan 3, 2014 at 9:37 AM, Doug Smythies wrote: >> However, I think item 7, translations and the overall workflow is >> the unknown at this time, and could be a major hurtle or even a >> show stopper. We need to estimate that part of the project for >> feasibility, person hours, and potential timeline for implementation. >> Myself, I would put a hold on items 1-6 for now. >> Myself, I do not know how to even start looking into item 7, but >> I'll help if possible. > > Huge +1 here. This is an LTS release and I'm not sure this is the best > time to take upon this major overhaul given the amount of time > involved and the uncertainty about translations. Translations are very > important, particularly in an LTS, and we do a great disservice to our > translations volunteers if we do this without a plan for them, or > otherwise abruptly change things for them. How ever we do this, it's > likely that all strings will be shown as modified and they'll have to > begin translations from scratch rather than just updating changed > strings. > > I'd feel much better doing this for 14.10, when it's a bit less > important to have a solid, translated documentation for release. As we know, there is a chorus that goes up at every UDS that says we should change away from XML but no one ever did anything. I decided to push forward with this in order to i) see what would be involved and ii) provoke reactions from people. From what I can see I've achieved both goals. It would be great if a knowledgeable person from Translations could get in contact with me about the impact this transition would have for them. ~pmatulis -- ubuntu-server mailing list ubuntu-server@lists.ubuntu.com https://lists.ubuntu.com/mailman/listinfo/ubuntu-server More info: https://wiki.ubuntu.com/ServerTeam
Re: Calling for Server Guide reviewers/contributors - - TRUSTY
On Fri, Jan 3, 2014 at 9:37 AM, Doug Smythies wrote: > However, I think item 7, translations and the overall workflow is > the unknown at this time, and could be a major hurtle or even a > show stopper. We need to estimate that part of the project for > feasibility, person hours, and potential timeline for implementation. > Myself, I would put a hold on items 1-6 for now. > Myself, I do not know how to even start looking into item 7, but > I'll help if possible. Huge +1 here. This is an LTS release and I'm not sure this is the best time to take upon this major overhaul given the amount of time involved and the uncertainty about translations. Translations are very important, particularly in an LTS, and we do a great disservice to our translations volunteers if we do this without a plan for them, or otherwise abruptly change things for them. How ever we do this, it's likely that all strings will be shown as modified and they'll have to begin translations from scratch rather than just updating changed strings. I'd feel much better doing this for 14.10, when it's a bit less important to have a solid, translated documentation for release. -- Elizabeth Krumbach Joseph || Lyz || pleia2 http://www.princessleia.com -- ubuntu-server mailing list ubuntu-server@lists.ubuntu.com https://lists.ubuntu.com/mailman/listinfo/ubuntu-server More info: https://wiki.ubuntu.com/ServerTeam
RE: Calling for Server Guide reviewers/contributors - - TRUSTY
On 2014.01.03 07:58 Peter Matulis wrote: > On 01/03/2014 10:43 AM, Peter Matulis wrote: >> On 01/03/2014 01:08 AM, Mauricio Tavares wrote: >>> I can help; it would be a good way to understand the new format. >>> Should I do what you did and fetch a chapter somehow, edit it and >>> place it somewhere so it can be seen before brought back? >> >> Let's work from here: >> >> https://code.launchpad.net/~petermatulis/+junk/serverguide-rst >> >> You can make a branch of that and then I can occasionally merge in your >> new work. > Mauricio, and anyone else, start by looking at installation.rst. It > contains good samples of the new way of doing things. For the > cross-reference link to the 'Aptitude' heading you will also need to > look at package-management.rst. Also adding back: On 2014.01.02 20:58 Peter had written: > After having spent a good part of the day going through just one file > (chapter) I now know how much work is involved: > 1. A good number of external links are broken > 2. All internal links are broken and require a new way of linking > (source and destination) > 3. All admonitions (i.e. "notes" and "warnings") are crippled, but not > outright broken > 4. All working external links *should* be changed to a new format > 5. Heading organization need to be redone in all chapters. All chapters > have multiple 1st level headings. This is what was causing the > flattened/expansize table of contents I mentioned earlier. > 6. More theme/customization work > 7. Research how this conversion will affect the translators and come up > with a corrective plan > I can't do all this myself; I estimate there is about 120 hours of work > required. Anyone? It is just my opinion, but I think we are getting ahead of ourselves here. Peter has a come up with an estimate for items 1-6, which is good. Some contingency time should be added to that estimate for issues not yet discovered (for example some tables are missing completely and some are not). For example, we are still finding issues with the "new" theme in the existing server guide after 2 almost two years. However, I think item 7, translations and the overall workflow is the unknown at this time, and could be a major hurtle or even a show stopper. We need to estimate that part of the project for feasibility, person hours, and potential timeline for implementation. Myself, I would put a hold on items 1-6 for now. Myself, I do not know how to even start looking into item 7, but I'll help if possible. ... Doug -- ubuntu-server mailing list ubuntu-server@lists.ubuntu.com https://lists.ubuntu.com/mailman/listinfo/ubuntu-server More info: https://wiki.ubuntu.com/ServerTeam
Re: Calling for Server Guide reviewers/contributors - - TRUSTY
On 01/03/2014 10:57 AM, Peter Matulis wrote: > On 01/03/2014 10:43 AM, Peter Matulis wrote: >> On 01/03/2014 01:08 AM, Mauricio Tavares wrote: > >>> I can help; it would be a good way to understand the new format. >>> Should I do what you did and fetch a chapter somehow, edit it and >>> place it somewhere so it can be seen before brought back? >> >> Let's work from here: >> >> https://code.launchpad.net/~petermatulis/+junk/serverguide-rst >> >> You can make a branch of that and then I can occasionally merge in your >> new work. > > Mauricio, and anyone else, start by looking at installation.rst. It > contains good samples of the new way of doing things. For the > cross-reference link to the 'Aptitude' heading you will also need to > look at package-management.rst. Don't forget to install Sphinx. $ sudo apt-get install sphinx-doc peter -- ubuntu-server mailing list ubuntu-server@lists.ubuntu.com https://lists.ubuntu.com/mailman/listinfo/ubuntu-server More info: https://wiki.ubuntu.com/ServerTeam
Re: Calling for Server Guide reviewers/contributors - - TRUSTY
On 01/03/2014 10:43 AM, Peter Matulis wrote: > On 01/03/2014 01:08 AM, Mauricio Tavares wrote: >> I can help; it would be a good way to understand the new format. >> Should I do what you did and fetch a chapter somehow, edit it and >> place it somewhere so it can be seen before brought back? > > Let's work from here: > > https://code.launchpad.net/~petermatulis/+junk/serverguide-rst > > You can make a branch of that and then I can occasionally merge in your > new work. Mauricio, and anyone else, start by looking at installation.rst. It contains good samples of the new way of doing things. For the cross-reference link to the 'Aptitude' heading you will also need to look at package-management.rst. peter -- ubuntu-server mailing list ubuntu-server@lists.ubuntu.com https://lists.ubuntu.com/mailman/listinfo/ubuntu-server More info: https://wiki.ubuntu.com/ServerTeam
Re: Calling for Server Guide reviewers/contributors - - TRUSTY
On 01/03/2014 01:08 AM, Mauricio Tavares wrote: > On Fri, Jan 3, 2014 at 5:58 AM, Peter Matulis >> After having spent a good part of the day going through just one file >> (chapter) I now know how much work is involved: >> >> 1. A good number of external links are broken >> 2. All internal links are broken and require a new way of linking >> (source and destination) >> 3. All admonitions (i.e. "notes" and "warnings") are crippled, but not >> outright broken >> 4. All working external links *should* be changed to a new format >> 5. Heading organization need to be redone in all chapters. All chapters >> have multiple 1st level headings. This is what was causing the >> flattened/expansize table of contents I mentioned earlier. >> 6. More theme/customization work >> 7. Research how this conversion will affect the translators and come up >> with a corrective plan >> >> I can't do all this myself; I estimate there is about 120 hours of work >> required. Anyone? >> > I can help; it would be a good way to understand the new format. > Should I do what you did and fetch a chapter somehow, edit it and > place it somewhere so it can be seen before brought back? Let's work from here: https://code.launchpad.net/~petermatulis/+junk/serverguide-rst You can make a branch of that and then I can occasionally merge in your new work. peter -- ubuntu-server mailing list ubuntu-server@lists.ubuntu.com https://lists.ubuntu.com/mailman/listinfo/ubuntu-server More info: https://wiki.ubuntu.com/ServerTeam
Re: Calling for Server Guide reviewers/contributors - - TRUSTY
On 12/13/2013 01:25 AM, William Van Hevelingen wrote: > Yeah...looks like those didn't get converted. It shouldn't be that much > effort to fix all the headers. The internal links will have to be fixed > too, maybe a sed script can fix them up. > > I used sphinx to generate some html and posted it here: > > http://web.cecs.pdx.edu/~wvan/serverguide/remote-administration.html > > Not really sure how to make the index/homepage work yet but this is a > work in progress. :) > > Do you have any feedback so besides the other items you mentioned? > > Btw `make lintcheck` is awesome. It reports on all the broken external > links and we can hook it up to continuous integration. Here is my own attempt, including some branding. Feedback welcome. Yes, there are still broken links and the table of contents is too expansive. I really like the streamlined markup (see 'Show Source' at the bottom of the TOC). http://serverguide.papamike.ca:8081 ~pmatulis -- ubuntu-server mailing list ubuntu-server@lists.ubuntu.com https://lists.ubuntu.com/mailman/listinfo/ubuntu-server More info: https://wiki.ubuntu.com/ServerTeam
Re: Calling for Server Guide reviewers/contributors - - TRUSTY
Sounds good Short Message because it's send from my iPhone. > On Dec 13, 2013, at 9:56 PM, "Peter Matulis" > wrote: > >> On 12/13/2013 01:00 PM, Spencer Krum wrote: >> The other question is do we have to conform to some Ubuntu look and feel >> guide. Making the server guide look like opsschool will be pretty easy, >> making a theme that will look exactly like the server guide does now, >> with coloring and tinting and branding and such might be much harder. > > Yes, good point. > > Based on the level of contributions in the last 4 years the Ubuntu > Server Guide is on a trajectory of irrelevance. We've seen some good > contributions in the last couple of years (most notably the LXC and > Multipath chapters) but it has not been enough. > > It would be great if we could maintain the current look and feel but > it's not an impediment if not. I'm sure we could Ubuntu-fy it in some > way. The most important elements are: > > 1. Accurate information > 2. Improving contributions (the reason why we're considering dumping > Docbook). > > ~pmatulis > > > > > -- > ubuntu-server mailing list > ubuntu-server@lists.ubuntu.com > https://lists.ubuntu.com/mailman/listinfo/ubuntu-server > More info: https://wiki.ubuntu.com/ServerTeam -- ubuntu-server mailing list ubuntu-server@lists.ubuntu.com https://lists.ubuntu.com/mailman/listinfo/ubuntu-server More info: https://wiki.ubuntu.com/ServerTeam
Re: Calling for Server Guide reviewers/contributors - - TRUSTY
On 12/13/2013 01:00 PM, Spencer Krum wrote: > The other question is do we have to conform to some Ubuntu look and feel > guide. Making the server guide look like opsschool will be pretty easy, > making a theme that will look exactly like the server guide does now, > with coloring and tinting and branding and such might be much harder. Yes, good point. Based on the level of contributions in the last 4 years the Ubuntu Server Guide is on a trajectory of irrelevance. We've seen some good contributions in the last couple of years (most notably the LXC and Multipath chapters) but it has not been enough. It would be great if we could maintain the current look and feel but it's not an impediment if not. I'm sure we could Ubuntu-fy it in some way. The most important elements are: 1. Accurate information 2. Improving contributions (the reason why we're considering dumping Docbook). ~pmatulis -- ubuntu-server mailing list ubuntu-server@lists.ubuntu.com https://lists.ubuntu.com/mailman/listinfo/ubuntu-server More info: https://wiki.ubuntu.com/ServerTeam
Re: Calling for Server Guide reviewers/contributors - - TRUSTY
The other question is do we have to conform to some Ubuntu look and feel guide. Making the server guide look like opsschool will be pretty easy, making a theme that will look exactly like the server guide does now, with coloring and tinting and branding and such might be much harder. On Fri, Dec 13, 2013 at 9:11 AM, Peter Matulis wrote: > On 12/13/2013 01:25 AM, William Van Hevelingen wrote: > > Yeah...looks like those didn't get converted. It shouldn't be that much > > effort to fix all the headers. The internal links will have to be fixed > > too, maybe a sed script can fix them up. > > > > I used sphinx to generate some html and posted it here: > > > > http://web.cecs.pdx.edu/~wvan/serverguide/remote-administration.html > > > > Not really sure how to make the index/homepage work yet but this is a > > work in progress. :) > > > > Do you have any feedback so besides the other items you mentioned? > > As far as formats are concerned, I do agree that reStructuredText is the > what we should be primarily looking at. > > In one of your previous links I like the way this ended up: > > http://www.opsschool.org/en/latest/ > > With the exception of the way the table of contents works. If you > choose a chapter lower down the list it expands but the page refreshes > and you're back at the top and can't see that expansion. > > I wonder if we can pull this off for Trusty? It's a bold move and it > should involve the opinions of more people. This will impact > translators as well. > > ~pmatulis > > -- > ubuntu-server mailing list > ubuntu-server@lists.ubuntu.com > https://lists.ubuntu.com/mailman/listinfo/ubuntu-server > More info: https://wiki.ubuntu.com/ServerTeam > -- Spencer Krum (619)-980-7820 -- ubuntu-server mailing list ubuntu-server@lists.ubuntu.com https://lists.ubuntu.com/mailman/listinfo/ubuntu-server More info: https://wiki.ubuntu.com/ServerTeam
Re: Calling for Server Guide reviewers/contributors - - TRUSTY
On 12/13/2013 01:25 AM, William Van Hevelingen wrote: > Yeah...looks like those didn't get converted. It shouldn't be that much > effort to fix all the headers. The internal links will have to be fixed > too, maybe a sed script can fix them up. > > I used sphinx to generate some html and posted it here: > > http://web.cecs.pdx.edu/~wvan/serverguide/remote-administration.html > > Not really sure how to make the index/homepage work yet but this is a > work in progress. :) > > Do you have any feedback so besides the other items you mentioned? As far as formats are concerned, I do agree that reStructuredText is the what we should be primarily looking at. In one of your previous links I like the way this ended up: http://www.opsschool.org/en/latest/ With the exception of the way the table of contents works. If you choose a chapter lower down the list it expands but the page refreshes and you're back at the top and can't see that expansion. I wonder if we can pull this off for Trusty? It's a bold move and it should involve the opinions of more people. This will impact translators as well. ~pmatulis -- ubuntu-server mailing list ubuntu-server@lists.ubuntu.com https://lists.ubuntu.com/mailman/listinfo/ubuntu-server More info: https://wiki.ubuntu.com/ServerTeam
Re: Calling for Server Guide reviewers/contributors - - TRUSTY
Hello, Le 12/12/2013 23:15, Peter Matulis a écrit : > I don't see why not as long as i) we can achieve the same results in > terms of an actual installation and ii) do not leave people scratching > their heads. I'm alluding to the fact that performing manual steps is > part of learning the software's architecture and, in turn, is invaluable > in how to maintain/administer the installation. Since Juju replaces the > manual steps the text would need to replace them with corresponding > explanation. I think that the reference for installing Openstack 'manually' should remain the Openstack.org document : "Openstack Installation Guide for Ubuntu 12.04 (LTS)" http://docs.openstack.org/havana/install-guide/install/apt/content/ Juju specific instructions may better fit in the Server Guide, though I've heard mention of an Openstack specific juju guide during vUDS. But if Juju's instructions end up in the server guide, we must make sure that they remain valid through the life of the LTS Kind regards, ..Louis -- Louis Bouchard Software engineer, Cloud & Sustaining eng. Canonical Ltd Ubuntu support: http://canonical.com/support -- ubuntu-server mailing list ubuntu-server@lists.ubuntu.com https://lists.ubuntu.com/mailman/listinfo/ubuntu-server More info: https://wiki.ubuntu.com/ServerTeam
Re: Calling for Server Guide reviewers/contributors - - TRUSTY
Yeah...looks like those didn't get converted. It shouldn't be that much effort to fix all the headers. The internal links will have to be fixed too, maybe a sed script can fix them up. I used sphinx to generate some html and posted it here: http://web.cecs.pdx.edu/~wvan/serverguide/remote-administration.html Not really sure how to make the index/homepage work yet but this is a work in progress. :) Do you have any feedback so besides the other items you mentioned? Btw `make lintcheck` is awesome. It reports on all the broken external links and we can hook it up to continuous integration. On Thu, Dec 12, 2013 at 9:38 PM, Peter Matulis wrote: > On 12/12/2013 09:37 PM, William Van Hevelingen wrote: > > I did a quick proof of concept to see how it would work to migrate it > > from docbook to rst. The results are on my github [1]. It only took a > > few minutes to figure out how to migrate the content. I can work on > > getting the navigation working too if people like this. > > > > If decide we want to do RST. I think we should follow the same style as > > what opsschool [3, 4] did. They use sphinx [2] to manage the conversion > > to html/pdfs and it looks really good. > > > > [1] https://github.com/blkperl/ubuntu-serverguide > > [2] http://sphinx-doc.org/ > > [3] https://github.com/opsschool/curriculum > > [4] http://www.opsschool.org/en/latest/ > > Hey that's sweet. Thank you. > > Comparing the below two pages, it seems all internal links are broken > and the top block of links does not appear at all. > > https://help.ubuntu.com/13.10/serverguide/device-mapper-multipathing.html > https://github.com/blkperl/ubuntu-serverguide/blob/master/dm-multipath.rst > > ~pmatulis > -- Thanks, William -- ubuntu-server mailing list ubuntu-server@lists.ubuntu.com https://lists.ubuntu.com/mailman/listinfo/ubuntu-server More info: https://wiki.ubuntu.com/ServerTeam
Re: Calling for Server Guide reviewers/contributors - - TRUSTY
Good job William, This looks awesome. I think we'd get more contributors ( and i'd be more inclined to participate myself) if we went to rst from xml. On Thu, Dec 12, 2013 at 9:38 PM, Peter Matulis wrote: > On 12/12/2013 09:37 PM, William Van Hevelingen wrote: > > I did a quick proof of concept to see how it would work to migrate it > > from docbook to rst. The results are on my github [1]. It only took a > > few minutes to figure out how to migrate the content. I can work on > > getting the navigation working too if people like this. > > > > If decide we want to do RST. I think we should follow the same style as > > what opsschool [3, 4] did. They use sphinx [2] to manage the conversion > > to html/pdfs and it looks really good. > > > > [1] https://github.com/blkperl/ubuntu-serverguide > > [2] http://sphinx-doc.org/ > > [3] https://github.com/opsschool/curriculum > > [4] http://www.opsschool.org/en/latest/ > > Hey that's sweet. Thank you. > > Comparing the below two pages, it seems all internal links are broken > and the top block of links does not appear at all. > > https://help.ubuntu.com/13.10/serverguide/device-mapper-multipathing.html > https://github.com/blkperl/ubuntu-serverguide/blob/master/dm-multipath.rst > > ~pmatulis > > -- > ubuntu-server mailing list > ubuntu-server@lists.ubuntu.com > https://lists.ubuntu.com/mailman/listinfo/ubuntu-server > More info: https://wiki.ubuntu.com/ServerTeam > -- Spencer Krum (619)-980-7820 -- ubuntu-server mailing list ubuntu-server@lists.ubuntu.com https://lists.ubuntu.com/mailman/listinfo/ubuntu-server More info: https://wiki.ubuntu.com/ServerTeam
Re: Calling for Server Guide reviewers/contributors - - TRUSTY
On 12/12/2013 09:37 PM, William Van Hevelingen wrote: > I did a quick proof of concept to see how it would work to migrate it > from docbook to rst. The results are on my github [1]. It only took a > few minutes to figure out how to migrate the content. I can work on > getting the navigation working too if people like this. > > If decide we want to do RST. I think we should follow the same style as > what opsschool [3, 4] did. They use sphinx [2] to manage the conversion > to html/pdfs and it looks really good. > > [1] https://github.com/blkperl/ubuntu-serverguide > [2] http://sphinx-doc.org/ > [3] https://github.com/opsschool/curriculum > [4] http://www.opsschool.org/en/latest/ Hey that's sweet. Thank you. Comparing the below two pages, it seems all internal links are broken and the top block of links does not appear at all. https://help.ubuntu.com/13.10/serverguide/device-mapper-multipathing.html https://github.com/blkperl/ubuntu-serverguide/blob/master/dm-multipath.rst ~pmatulis -- ubuntu-server mailing list ubuntu-server@lists.ubuntu.com https://lists.ubuntu.com/mailman/listinfo/ubuntu-server More info: https://wiki.ubuntu.com/ServerTeam
Re: Calling for Server Guide reviewers/contributors - - TRUSTY
I did a quick proof of concept to see how it would work to migrate it from docbook to rst. The results are on my github [1]. It only took a few minutes to figure out how to migrate the content. I can work on getting the navigation working too if people like this. If decide we want to do RST. I think we should follow the same style as what opsschool [3, 4] did. They use sphinx [2] to manage the conversion to html/pdfs and it looks really good. [1] https://github.com/blkperl/ubuntu-serverguide [2] http://sphinx-doc.org/ [3] https://github.com/opsschool/curriculum [4] http://www.opsschool.org/en/latest/ ~blkperl On Thu, Dec 12, 2013 at 2:15 PM, Peter Matulis wrote: > On 12/12/2013 04:03 PM, Jorge O. Castro wrote: > > On Thu, Dec 12, 2013 at 8:57 AM, Peter Matulis > > wrote: > >> This is mentioned at every UDS but no one ever steps up to do anything > >> so we remain with XML. > > > > What's involved with this? > > 1. Ensuring the underlying source can yield HTML and PDF documents. > > 2. Convert *all* XML to the new format and then convert *all* of the > latter to HTML *and* PDF and make sure *everything* looks right. > > 3. The toolchain needs to be understandable by mortals. > > (a) Will we lose "linkend" attributes? That is, the ability to do: > > > If you are going to use LDAP to store Samba users you will need to > configure the Samba > server to authenticate using LDAP. See for > details. > > > I'm not sure how these kinds of source links will end up after > converting from XML to markdown. > > (b) There may very well be other things we need to think about. I'm not > an XML expert. > > > Sections 10 through 14 need to be rewritten for Juju usage. > > I don't see why not as long as i) we can achieve the same results in > terms of an actual installation and ii) do not leave people scratching > their heads. I'm alluding to the fact that performing manual steps is > part of learning the software's architecture and, in turn, is invaluable > in how to maintain/administer the installation. Since Juju replaces the > manual steps the text would need to replace them with corresponding > explanation. > > ~pmatulis > > -- > ubuntu-server mailing list > ubuntu-server@lists.ubuntu.com > https://lists.ubuntu.com/mailman/listinfo/ubuntu-server > More info: https://wiki.ubuntu.com/ServerTeam > -- Thanks, William -- ubuntu-server mailing list ubuntu-server@lists.ubuntu.com https://lists.ubuntu.com/mailman/listinfo/ubuntu-server More info: https://wiki.ubuntu.com/ServerTeam
Re: Calling for Server Guide reviewers/contributors - - TRUSTY
On 12/12/2013 04:03 PM, Jorge O. Castro wrote: > On Thu, Dec 12, 2013 at 8:57 AM, Peter Matulis > wrote: >> This is mentioned at every UDS but no one ever steps up to do anything >> so we remain with XML. > > What's involved with this? 1. Ensuring the underlying source can yield HTML and PDF documents. 2. Convert *all* XML to the new format and then convert *all* of the latter to HTML *and* PDF and make sure *everything* looks right. 3. The toolchain needs to be understandable by mortals. (a) Will we lose "linkend" attributes? That is, the ability to do: If you are going to use LDAP to store Samba users you will need to configure the Samba server to authenticate using LDAP. See for details. I'm not sure how these kinds of source links will end up after converting from XML to markdown. (b) There may very well be other things we need to think about. I'm not an XML expert. > Sections 10 through 14 need to be rewritten for Juju usage. I don't see why not as long as i) we can achieve the same results in terms of an actual installation and ii) do not leave people scratching their heads. I'm alluding to the fact that performing manual steps is part of learning the software's architecture and, in turn, is invaluable in how to maintain/administer the installation. Since Juju replaces the manual steps the text would need to replace them with corresponding explanation. ~pmatulis -- ubuntu-server mailing list ubuntu-server@lists.ubuntu.com https://lists.ubuntu.com/mailman/listinfo/ubuntu-server More info: https://wiki.ubuntu.com/ServerTeam
Re: Calling for Server Guide reviewers/contributors - - TRUSTY
On Thu, Dec 12, 2013 at 8:57 AM, Peter Matulis wrote: > This is mentioned at every UDS but no one ever steps up to do anything > so we remain with XML. What's involved with this? Sections 10 through 14 need to be rewritten for Juju usage. Is there a way people can contribute via markdown and then feed that through pandoc or something? I have no problems committing to contributing to the guide, but I'm not going to rewrite 4 chapters in docbook. -- Jorge Castro Canonical Ltd. http://juju.ubuntu.com/ - Automate your Cloud Infrastructure -- ubuntu-server mailing list ubuntu-server@lists.ubuntu.com https://lists.ubuntu.com/mailman/listinfo/ubuntu-server More info: https://wiki.ubuntu.com/ServerTeam
Re: Calling for Server Guide reviewers/contributors - - TRUSTY
On 12/12/2013 12:07 AM, William Van Hevelingen wrote: > Any update on the items in the blueprint? > > https://blueprints.launchpad.net/serverguide/+spec/community-1308-serverguide-development > > (a) Settle on an XML editor that will make editing the source files easier I was actually looking at this yesterday. The primary candidate was XEE (XMLmind XML Editor), a lush graphical tool, but it's not free (30-day evaluation edition available). I also looked at asciicode [1]. It changes the paradigm by allowing one to use its own simple wiki-style syntax and then have that converted to XML. I stopped looking at it when I realized it could lead to a lot of non-standard XML unless everyone was using it, making things even more confusing. This may not be the case so there is still potential here. [1]: http://asciidoc.org/ Other editors are mentioned here: http://stackoverflow.com/questions/3429557/xml-editing-in-linux Personally I use just use vim. : ) > (b) Possibly moving away from the XML format, for the same reason This is mentioned at every UDS but no one ever steps up to do anything so we remain with XML. ~peter -- ubuntu-server mailing list ubuntu-server@lists.ubuntu.com https://lists.ubuntu.com/mailman/listinfo/ubuntu-server More info: https://wiki.ubuntu.com/ServerTeam
Re: Calling for Server Guide reviewers/contributors - - TRUSTY
Any update on the items in the blueprint? https://blueprints.launchpad.net/serverguide/+spec/community-1308-serverguide-development (a) Settle on an XML editor that will make editing the source files easier (b) Possibly moving away from the XML format, for the same reason I've contributed before and every time it reminds me how horrible it is to have docs in XML. +1 for moving to something like markdown or restructured text. Cheers, William On Wed, Dec 11, 2013 at 9:43 AM, Peter Matulis wrote: > Hi everybody. > > We're always in need of folks to review current instructions provided in > the Ubuntu Server Guide and suggest improvements. Please do check out > the following link and help out where you can. > > > https://wiki.ubuntu.com/DocumentationTeam/SystemDocumentation/UbuntuServerGuide > > The subjects we need the most help with this cycle are the following > (also documented above): > > Zentyal > Network Authentication - Samba and LDAP > DNS Troubleshooting > AppArmor > TLS Certificates > eCryptfs > Monitoring - Overview > Monitoring - Nagios > Monitoring - Munin > Apache > Ruby on Rails > phpMyAdmin > Exim4 > Mailman > MailFiltering > Version Control Systems - References > Samba - Introduction > Samba - File Server > Samba - Print Server > Samba - Securing File and Print Server > Samba - As a Domain Controller > Samba - Active Directory Integration > JeOS and vmbuilder (scheduled for removal) > Ubuntu Cloud (will probably redirect to upstream docs) > OpenVPN > > Instead of helping on a per-topic basis you can also offer fixes to > existing bugs: > > https://bugs.launchpad.net/serverguide > > We're also looking for help in maintaining the guide in terms of > validating reviews (merge proposals). > > Thanks! > > Peter Matulis > > -- > ubuntu-server mailing list > ubuntu-server@lists.ubuntu.com > https://lists.ubuntu.com/mailman/listinfo/ubuntu-server > More info: https://wiki.ubuntu.com/ServerTeam > -- Thanks, William -- ubuntu-server mailing list ubuntu-server@lists.ubuntu.com https://lists.ubuntu.com/mailman/listinfo/ubuntu-server More info: https://wiki.ubuntu.com/ServerTeam
