> On 2 Jan 2015, at 16:25, Maruan Sahyoun <sahy...@fileaffairs.de> wrote: > >> >> >>> On 1 Jan 2015, at 22:23, Maruan Sahyoun <sahy...@fileaffairs.de >>> <mailto:sahy...@fileaffairs.de>> wrote: >>> >>> Hi John, >>> >>>> >>>>> On 1 Jan 2015, at 14:40, Maruan Sahyoun <sahy...@fileaffairs.de >>>>> <mailto:sahy...@fileaffairs.de> <mailto:sahy...@fileaffairs.de >>>>> <mailto:sahy...@fileaffairs.de>>> wrote: >>>>> >>>>> >>>>>> This isn’t a good situation at all, we had a usable documentation system >>>>>> in October and now we have nothing usable, with almost no content and no >>>>>> way to easily contribute. >>>>> >>>>> how is the content different from the existing one? There wasn't a lot of >>>>> content and there still isn't. That usable documentation system wasn't >>>>> used a lot. >>>> >>>> Most of the website is missing, all we have is the cookbook. There’s no >>>> way to build, deploy or preview anything. >>>> >>> >>> it's not meant to replace the whole website. That will still reside in the >>> Apache CMS which will pull the docs sources from GitHub (I explained that >>> in a ticket). >> >> Do you mean PDFBOX-2340? I assumed that “pdfbox docs” meant our entire >> website. I guess not. So this means we have some of the website on SVN and >> some of it on Git? And no single revision number for the overall site? > > The discussion before pdfbox-docs has been created was to have the > documentation on git not the overall website. The build system ist still the > Apache CMS as is currently in use. That will have the templates, the build > scripts …. - as is today. > >> >>> pdfbox-docs will hold the sources for the documentation. I brought the >>> cookbook entries so one can see some of the structure. >> >> What about the other existing docs? How do I contribute to those? On SVN? >> >>>>> >>>>>> We’d agreed that moving to docs to GitHub was an experiment to see if it >>>>>> made contributing easier but it’s had the opposite effect, we’re in a >>>>>> less usable state than ever. It seems like we’d be better off going back >>>>>> to our working SVN documentation and creating a new 2.0 branch from the >>>>>> 1.8 docs and then updating them. We just haven’t realised the benefit >>>>>> from doing things differently. >>>>> >>>>> There were no major contributions to the documentation using SVN. >>>>> Everybody could have done it before but didn't. The non existing content >>>>> is not because of GitHub (or SVN). >>>> >>>> If there’s no advantage to using GitHub then we probably shouldn’t use it. >>>> This was a test to see if there were benefits… but there seem to be none. >>>> >>>>> So my suggestion is to put the content you are planning to contribute >>>>> into pdfbox-docs. Now if you put it into the CMS fine. We can later make >>>>> it available in pdfbox-docs. >>>> >>>> I’d like to do that, but unless I need to be able to build and deploy the >>>> docs to the website somehow. >>>> >>>>> I take some of the blame as I didn't find the time to enhance/restructure >>>>> the website - again that's not GitHubs fault. >>>> >>>> Enhancements are of course welcome, but we need the old functionality >>>> working, at a bare minimum. e.g. where has most of the website gone? >>>> >>> >>> the restructuring is necessary because the pull mechanism needs to be >>> enabled. >>> >>> In addition there needs to be the place for the PDFBox 2 docs together with >>> the old 1.8 docs. That's independent from using SVN or GitHub. >> >> All we need is a branch in SVN. There’s no need to put the 1.8 docs on >> GitHub, they’re going to obsolete in a few months. The simplest possible >> solution is to just create a new 2.0 docs branch on SVN. >> > > That's revisiting the git/svn discussion. If there is agreement that it shall > stay on SVN fine. > >>> I have a little more time now so can look into that (and put the AcroForm >>> stuff to the side for the moment). OTOH if you or someone else wants to do >>> it let me know. >> >> I’m a little stuck to be honest, it seems that our documentation system is >> currently non-functional and part of it is on git for no clear reason… >> > > We had the git discussion before pdfbox-docs has been created. If we want to > revisit that we can always do. > > Other than that there is a functional documentation system. You can add to > the documentation today using svn only or together with pdfbox-docs, do a > local build for testing and submit your changes.
What is the workflow for updating pdfbox-docs and pushing it to the website? If I make a change to pdfbox-docs what else do I have to do to get that published on the website? > Now there is no sample doing it this way in the PDFBox CMS sources as I > didn't have the time yet to create one. The Apache CMS capabilities are > documented at http://www.apache.org/dev/cmsref.html > <http://www.apache.org/dev/cmsref.html>. Some of the more advanced > capabilities are not well documented but need to be gathered by inspecting > the code or looking at other projects using the Apache CMS. > > BTW no need to wait for me doing these changes as every committer has access. > > > BR > Maruan > >>> BR - Maruan >>> >>>>> Maruan >>>>> >>>>> >>>>>> >>>>>> -- John >>>>>> >>>>>>> On 1 Jan 2015, at 12:52, Maruan Sahyoun <sahy...@fileaffairs.de> wrote: >>>>>>> >>>>>>> the docs shall reside in pdfbox-docs from where they will be pulled >>>>>>> onto the website or looked at directly at github. >>>>>>> >>>>>>> The publishing process to our website is not yet in place as there is >>>>>>> no new content. I'm looking to get the redesign of the website done to >>>>>>> accommodate for the old 1.8 and new 2.0 release. >>>>>>> >>>>>>> Maruan >>>>>>> >>>>>>> Am 01.01.2015 um 19:38 schrieb John Hewson <j...@jahewson.com>: >>>>>>> >>>>>>>> Hi All, >>>>>>>> >>>>>>>> We’re getting closer to 2.0 being ready and I’m thinking about writing >>>>>>>> some docs, but currently the situation seems to be worse than it was >>>>>>>> before the docs stated moving to GitHub - where are our canonical docs >>>>>>>> and how can I contribute to them? >>>>>>>> >>>>>>>> All I see on GitHub is some old 1.8 stuff and an incomplete cookbook >>>>>>>> for forms. Is this content live anywhere? Is there a pay to preview it? >>>>>>>> >>>>>>>> -- John
