commit 331982f836416ecff70a64c941c0e0f6c263460a Author: Nima Fatemi mrphs@riseup.net Date: Fri Nov 14 23:40:26 2014 +0000
Update and rename README to README.md
- Applying markdown format and some prettifying. - Adding a note to arma's instruction. --- README | 79 ---------------------------------------------------------- README.md | 82 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 82 insertions(+), 79 deletions(-)
diff --git a/README b/README deleted file mode 100644 index 80afdc5..0000000 --- a/README +++ /dev/null @@ -1,79 +0,0 @@ -To quickly get set up simply do the following... - - 1. Get the website's build dependencies. - - % sudo apt-get install wml asciidoc - - 2. Configure where to find your tor git repository. It needs this to make the - manual page. - - % git clone https://git.torproject.org/project/web/webwml.git - % cd webwml - % cp Makefile.local.sample Makefile.local - [ change the TORGIT in Makefile.local to point to your tor git repo ] - - 3. Make the website. - - % make - -You should now be able to point your browser at the locally generated site... - - file:///home/atagar/Desktop/tor/webwml/getinvolved/volunteer.html.en - --------------------------------------------------------------------------------- -Troubleshooting --------------------------------------------------------------------------------- - -* The build fails with "Invalid object name". - - If you get an error like... - - ---- Contents of STDERR channel: --------- - fatal: Invalid object name 'tor-0.2.6.1-alpha'. - asciidoc: FAILED: manpage document title is mandatory - No manpage because of asciidoc error or file not available from git at /tmp/wml.zwcq0q/wml.30867.tmp1.wml line 415. - - This means your tor repository is out of date. Update your tor git repository. - --------------------------------------------------------------------------------- -More detailed instructions from Roger --------------------------------------------------------------------------------- - -Here are the instructions I sent David Fifield when he asked about -editing the website. I hope they are useful for you too! --Roger - -Copy Makefile.local.sample to Makefile.local in your webwml/ directory. -Point TORGIT to a tor git. - -Then apt-get install wml and (alas) probably a shocking number of other -debs. Then you can type 'make' and it will build the website for you -locally. It's probably a smart move to see whether 'make' works before -you git commit any changes to the wml files. - -You can edit docs/en/pluggable-transports.wml (and that is -the right source file to edit, not the html). But go take a -look at that file. You'll notice it has a bunch of tags like -<version-torbrowserbundle>. If you're just bumping version -numbers, you probably just want to change the definition of those tags. -They're in include/versions.wmi - -(Every once in a while you may need to edit pluggable-transports.wml -too -- generally when you change the file name so drastically that just -changing the versions.wmi tags isn't enough.) - -Pushes to the master branch of the git repository will cause the -website to get re-built and published. Pushing to the staging branch -will update www-staging.torproject.org. - -Alas, https://www.torproject.org/dist/ isn't in version control. You -write to it by ssh'ing to dist-master.torproject.org and going to -/srv/dist-master.torproject.org/htdocs/ and then sticking your stuff -there. When you want it to go live, you run -"static-update-component dist.torproject.org" on dist-master. - -Weasel has hopes that somebody will write some scripts to make maintaining -packages in dist/ less awful -- automatically check that they have -signatures and that the sigs match, that the items on the website are in -fact in dist, only allow certain people to put files in certain places, -etc. One day! :) - diff --git a/README.md b/README.md new file mode 100644 index 0000000..173f97e --- /dev/null +++ b/README.md @@ -0,0 +1,82 @@ +# Building website locally + +To quickly get set up simply do the following + + __Step 1:__ Get the website's build dependencies. + + sudo apt-get install wml asciidoc + + __Step 2:__ Configure where to find your tor git repository. It needs this to make the + manual page. + + git clone https://git.torproject.org/project/web/webwml.git + cd webwml + cp Makefile.local.sample Makefile.local + +Note: Change the `TORGIT` in Makefile.local to point to your tor git repo. + + __Step 3:__ Make the website. + + make + +You should now be able to point your browser at the locally generated site... + + file:///home/atagar/Desktop/tor/webwml/getinvolved/volunteer.html.en + + +### Troubleshooting the build + +The build fails with "Invalid object name". + + If you get an error like... + + ---- Contents of STDERR channel: --------- + fatal: Invalid object name 'tor-0.2.6.1-alpha'. + asciidoc: FAILED: manpage document title is mandatory + No manpage because of asciidoc error or file not available from git at /tmp/wml.zwcq0q/wml.30867.tmp1.wml line 415. + + This means your tor repository is out of date. Update your tor git repository. + + +### More detailed instructions from Roger + +_Note: This section was written when website repo was still on svn, and it wasn't built automatically._ + +Here are the instructions I sent David Fifield when he asked about +editing the website. I hope they are useful for you too! --Roger + +Copy Makefile.local.sample to Makefile.local in your webwml/ directory. +Point TORGIT to a tor git. + +Then apt-get install wml and (alas) probably a shocking number of other +debs. Then you can type 'make' and it will build the website for you +locally. It's probably a smart move to see whether 'make' works before +you git commit any changes to the wml files. + +You can edit docs/en/pluggable-transports.wml (and that is +the right source file to edit, not the html). But go take a +look at that file. You'll notice it has a bunch of tags like +<version-torbrowserbundle>. If you're just bumping version +numbers, you probably just want to change the definition of those tags. +They're in include/versions.wmi + +(Every once in a while you may need to edit pluggable-transports.wml +too -- generally when you change the file name so drastically that just +changing the versions.wmi tags isn't enough.) + +Pushes to the master branch of the git repository will cause the +website to get re-built and published. Pushing to the staging branch +will update www-staging.torproject.org. + +Alas, https://www.torproject.org/dist/ isn't in version control. You +write to it by ssh'ing to dist-master.torproject.org and going to +/srv/dist-master.torproject.org/htdocs/ and then sticking your stuff +there. When you want it to go live, you run +"static-update-component dist.torproject.org" on dist-master. + +Weasel has hopes that somebody will write some scripts to make maintaining +packages in dist/ less awful -- automatically check that they have +signatures and that the sigs match, that the items on the website are in +fact in dist, only allow certain people to put files in certain places, +etc. One day! :) +