> >> On 1 Jan 2015, at 22:23, Maruan Sahyoun <sahy...@fileaffairs.de> wrote: >> >> Hi John, >> >>> >>>> On 1 Jan 2015, at 14:40, Maruan Sahyoun <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. 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. 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 >
